Instruction:
Can you generate the documentation for the following Python 3 function
def plfit(self, nosmall=True, finite=False, quiet=False, silent=False,
              usefortran=False, usecy=False, xmin=None, verbose=False,
              discrete=None, discrete_approx=True, discrete_n_alpha=1000,
              skip_consistency_check=False):
        """
        A Python implementation of the Matlab code
        http://www.santafe.edu/~aaronc/powerlaws/plfit.m
        from http://www.santafe.edu/~aaronc/powerlaws/

        See A. Clauset, C.R. Shalizi, and M.E.J. Newman, "Power-law distributions
        in empirical data" SIAM Review, 51, 661-703 (2009). (arXiv:0706.1062)
        http://arxiv.org/abs/0706.1062

        There are 3 implementations of xmin estimation.  The fortran version is
        fastest, the C (cython) version is ~10% slower, and the python version
        is ~3x slower than the fortran version.  Also, the cython code suffers
        ~2% numerical error relative to the fortran and python for unknown
        reasons.

        There is also a discrete version implemented in python - it is
        different from the continous version!

        Parameters
        ----------
        discrete : bool or None
            If *discrete* is None, the code will try to determine whether the
            data set is discrete or continous based on the uniqueness of the
            data; if your data set is continuous but you have any non-unique
            data points (e.g., flagged "bad" data), the "automatic"
            determination will fail.  If *discrete* is True or False, the
            discrete or continuous fitter will be used, respectively.
        xmin : float or int
            If you specify xmin, the fitter will only determine alpha assuming
            the given xmin; the rest of the code (and most of the complexity)
            is determining an estimate for xmin and alpha.
        nosmall : bool
            When on, the code rejects low s/n points.  WARNING: This option,
            which is on by default, may result in different answers than the
            original Matlab code and the "powerlaw" python package
        finite : bool
            There is a 'finite-size bias' to the estimator.  The "alpha" the
            code measures is "alpha-hat" s.t. ᾶ = (nα-1)/(n-1), or α = (1 + ᾶ
            (n-1)) / n
        quiet : bool
            If False, delivers messages about what fitter is used and the fit
            results
        verbose : bool
            Deliver descriptive messages about the fit parameters (only if
            `quiet==False`)
        silent : bool
            If True, will print NO messages
        skip_consistency_check : bool
            The code will normally perform a consistency check to make sure the
            alpha value computed by the fitter matches the alpha value computed
            directly in python.  It is possible for numerical differences to
            creep in, usually at the 10^-6 or less level.  If you see an
            exception reporting this type of error, skipping the check can be
            the appropriate next step.

        Returns
        -------
        (xmin, alpha)
        The best-fit xmin and alpha values
        """
        x = self.data
        if any(x < 0):
            raise ValueError("Power law distributions are only valid for "
                             "positive data.  Remove negative values before "
                             "fitting.")
        z = np.sort(x)

        # xmins = the unique values of x that can be used as the threshold for
        # the power law fit
        # argxmins = the index of each of these possible thresholds
        xmins,argxmins = np.unique(z,return_index=True)
        self._nunique = len(xmins)

        if self._nunique == len(x) and discrete is None:
            if verbose:
                print("Using CONTINUOUS fitter because there are no repeated "
                      "values.")
            discrete = False
        elif self._nunique < len(x) and discrete is None:
            if verbose:
                print("Using DISCRETE fitter because there are repeated "
                      "values.")
            discrete = True

        t = time.time()
        if xmin is None:
            if discrete:
                self.discrete_best_alpha(approximate=discrete_approx,
                                         n_alpha=discrete_n_alpha,
                                         verbose=verbose,
                                         finite=finite)
                return self._xmin,self._alpha
            elif usefortran and fortranOK:
                kstest_values,alpha_values = fplfit.plfit(z, 0)
                if not quiet:
                    print(("FORTRAN plfit executed in %f seconds" % (time.time()-t)))
            elif usecy and cyOK:
                kstest_values,alpha_values = cplfit.plfit_loop(z,
                                                               nosmall=False,
                                                               zunique=xmins,
                                                               argunique=argxmins)
                if not quiet:
                    print(("CYTHON plfit executed in %f seconds" % (time.time()-t)))
            else:
                # python (numpy) version
                f_alpha = alpha_gen(z)
                f_kstest = kstest_gen(z)
                alpha_values = np.asarray(list(map(f_alpha,xmins)),
                                          dtype='float')
                kstest_values = np.asarray(list(map(f_kstest,xmins)),
                                           dtype='float')
                if not quiet:
                    print(("PYTHON plfit executed in %f seconds" % (time.time()-t)))

            if not quiet:
                if usefortran and not fortranOK:
                    raise ImportError("fortran fplfit did not load")
                if usecy and not cyOK:
                    raise ImportError("cython cplfit did not load")

            # For each alpha, the number of included data points is
            # total data length - first index of xmin
            # No +1 is needed: xmin is included.
            sigma = (alpha_values-1)/np.sqrt(len(z)-argxmins)
            # I had changed it to this, but I think this is wrong.
            # sigma = (alpha_values-1)/np.sqrt(len(z)-np.arange(len(z)))

            if nosmall:
                # test to make sure the number of data points is high enough
                # to provide a reasonable s/n on the computed alpha
                goodvals = sigma<0.1
                nmax = argmin(goodvals)
                if nmax <= 0:
                    nmax = len(xmins) - 1
                    if not silent:
                        print("Not enough data left after flagging "
                              "low S/N points.  "
                              "Using all data.")
            else:
                # -1 to weed out the very last data point; it cannot be correct
                # (can't have a power law with 1 data point).
                nmax = len(xmins)-1

            best_ks_index = argmin(kstest_values[:nmax])
            xmin = xmins[best_ks_index]

            self._alpha_values = alpha_values
            self._xmin_kstest = kstest_values
            if scipyOK:
                # CHECK THIS
                self._ks_prob_all = np.array([scipy.stats.ksone.sf(D_stat,
                                                                   len(kstest_values)-ii)
                                              for ii,D_stat in
                                              enumerate(kstest_values)])
            self._sigma = sigma

            # sanity check
            n = np.count_nonzero(z>=xmin)
            alpha = 1. + float(n)/sum(log(z[z>=xmin]/xmin))
            try:
                if not skip_consistency_check:
                    np.testing.assert_almost_equal(alpha,
                                                   alpha_values[best_ks_index],
                                                   decimal=4)
            except AssertionError:
                raise AssertionError("The alpha value computed was not self-"
                                     "consistent.  This should not happen.  "
                                     "However, it is possible that this is "
                                     "a numerical uncertainty issue; the "
                                     "values being compared are {0} and {1}."
                                     "If they are close enough, set "
                                     "skip_consistency_check=True."
                                     .format(alpha,
                                             alpha_values[best_ks_index]))

        z = z[z>=xmin]
        n = len(z)
        alpha = 1. + float(n) / sum(log(z/xmin))
        if finite:
            alpha = alpha*(n-1.)/n+1./n
        if n < 50 and not finite and not silent:
            print(('(PLFIT) Warning: finite-size bias may be present. n=%i' % n))

        ks = max(abs( np.arange(n)/float(n) - (1-(xmin/z)**(alpha-1)) ))
        # Parallels Eqn 3.5 in Clauset et al 2009, but zeta(alpha, xmin) =
        # (alpha-1)/xmin.  Really is Eqn B3 in paper.
        L = n*log((alpha-1)/xmin) - alpha*sum(log(z/xmin))
        #requires another map... Larr = arange(len(unique(x))) * log((alpha_values-1)/unique(x)) - alpha_values*sum
        self._likelihood = L
        self._xmin = xmin
        self._xmins = xmins
        self._alpha= alpha
        self._alphaerr = (alpha-1)/np.sqrt(n)

        # this ks statistic may not have the same value as min(dat) because of unique()
        self._ks = ks

        if scipyOK:
            self._ks_prob = scipy.stats.ksone.sf(ks, n)

        self._ngtx = n
        if n == 1:
            if not silent:
                print("Failure: only 1 point kept.  Probably not a power-law distribution.")
            self._alpha = alpha = 0
            self._alphaerr = 0
            self._likelihood = L = 0
            self._ks = 0
            self._ks_prob = 0
            self._xmin = xmin
            return xmin,0
        if np.isnan(L) or np.isnan(xmin) or np.isnan(alpha):
            raise ValueError("plfit failed; returned a nan")

        if not quiet:
            if verbose: print("The lowest value included in the power-law fit, ", end=' ')
            print("xmin: %g" % xmin, end=' ')
            if verbose: print("\nThe number of values above xmin, ", end=' ')
            print("n(>xmin): %i" % n, end=' ')
            if verbose: print("\nThe derived power-law alpha (p(x)~x^-alpha) with MLE-derived error, ", end=' ')
            print("alpha: %g +/- %g  " % (alpha,self._alphaerr), end=' ')
            if verbose: print("\nThe log of the Likelihood (the maximized parameter; you minimized the negative log likelihood), ", end=' ')
            print("Log-Likelihood: %g  " % L, end=' ')
            if verbose: print("\nThe KS-test statistic between the best-fit power-law and the data, ", end=' ')
            print("ks: %g" % (ks), end=' ')
            if scipyOK:
                if verbose: print(" occurs with probability  ", end=' ')
                print("p(ks): %g" % (self._ks_prob))
            else:
                print()

        return xmin,alpha

Response: This function is a wrapper for the Pfit function in the general case.


Instruction:
Create a Python 3 function to
return the discrete best alpha value for the current entry.

Response:
def discrete_best_alpha(self, alpharangemults=(0.9,1.1), n_alpha=201,
                            approximate=True, verbose=True, finite=True):
        """
        Use the maximum likelihood to determine the most likely value of alpha

        *alpharangemults* [ 2-tuple ]
            Pair of values indicating multiplicative factors above and below the
            approximate alpha from the MLE alpha to use when determining the
            "exact" alpha (by directly maximizing the likelihood function)
        *n_alpha* [ int ]
            Number of alpha values to use when measuring.  Larger number is more accurate.
        *approximate* [ bool ]
            If False, try to "zoom-in" around the MLE alpha and get the exact
            best alpha value within some range around the approximate best
        *vebose* [ bool ]
        *finite* [ bool ]
            Correction for finite data?
        """

        data = self.data
        self._xmins = xmins = np.unique(data)
        if approximate:
            alpha_of_xmin = [ discrete_alpha_mle(data,xmin) for xmin in xmins ]
        else:
            alpha_approx = [ discrete_alpha_mle(data,xmin) for xmin in xmins ]
            alpharanges = [(0.9*a,1.1*a) for a in alpha_approx]
            alpha_of_xmin = [ most_likely_alpha(data,xmin,alpharange=ar,n_alpha=n_alpha)
                             for xmin,ar in zip(xmins,alpharanges) ]
        ksvalues = np.array([discrete_ksD(data, xmin, alpha)
                                for xmin,alpha in zip(xmins,alpha_of_xmin)
                               ])
        self._alpha_values = np.array(alpha_of_xmin)
        self._xmin_kstest = ksvalues

        ksvalues[np.isnan(ksvalues)] = np.inf

        best_index = argmin(ksvalues)
        self._alpha = best_alpha = alpha_of_xmin[best_index]
        self._xmin = best_xmin = xmins[best_index]
        self._ks = best_ks = ksvalues[best_index]
        self._likelihood = best_likelihood = discrete_likelihood(data, best_xmin, best_alpha)

        if finite:
            self._alpha = self._alpha*(n-1.)/n+1./n

        if verbose:
            print("alpha = %f   xmin = %f   ksD = %f   L = %f   (n<x) = %i  (n>=x) = %i" % (
                    best_alpha, best_xmin, best_ks, best_likelihood,
                    (data<best_xmin).sum(), (data>=best_xmin).sum()))

        self._ngtx = n = (self.data>=self._xmin).sum()
        self._alphaerr = (self._alpha-1.0)/np.sqrt(n)
        if scipyOK:
            self._ks_prob = scipy.stats.ksone.sf(self._ks, n)

        return best_alpha,best_xmin,best_ks,best_likelihood


Instruction:
Create a Python 3 function to
plot xmin versus the ks value for derived alpha.

Response:
def xminvsks(self, **kwargs):
        """
        Plot xmin versus the ks value for derived alpha.  This plot can be used
        as a diagnostic of whether you have derived the 'best' fit: if there are
        multiple local minima, your data set may be well suited to a broken
        powerlaw or a different function.
        """

        pylab.plot(self._xmins,self._xmin_kstest,'.')
        pylab.plot(self._xmin,self._ks,'s')
        #pylab.errorbar([self._ks],self._alpha,yerr=self._alphaerr,fmt='+')

        ax=pylab.gca()
        ax.set_ylabel("KS statistic")
        ax.set_xlabel("min(x)")
        pylab.draw()

        return ax


Instruction:
Can you generate a brief explanation for the following Python 3 code
def alphavsks(self,autozoom=True,**kwargs):

        pylab.plot(self._alpha_values, self._xmin_kstest, '.')
        pylab.errorbar(self._alpha, self._ks, xerr=self._alphaerr, fmt='+')

        ax=pylab.gca()
        if autozoom:
            ax.set_ylim(0.8*(self._ks),3*(self._ks))
            ax.set_xlim((self._alpha)-5*self._alphaerr,(self._alpha)+5*self._alphaerr)
        ax.set_ylabel("KS statistic")
        ax.set_xlabel(r'$\alpha$')
        pylab.draw()

        return ax

Response: Plot alpha versus the ks value for derived alpha.


Instruction:
Make a summary of the following Python 3 code
def plotcdf(self, x=None, xmin=None, alpha=None, pointcolor='k',
                dolog=True, zoom=True, pointmarker='+', **kwargs):
        """
        Plots CDF and powerlaw
        """
        if x is None: x=self.data
        if xmin is None: xmin=self._xmin
        if alpha is None: alpha=self._alpha

        x=np.sort(x)
        n=len(x)
        xcdf = np.arange(n,0,-1,dtype='float')/float(n)

        q = x[x>=xmin]
        fcdf = (q/xmin)**(1-alpha)
        nc = xcdf[argmax(x>=xmin)]
        fcdf_norm = nc*fcdf

        D_location = argmax(xcdf[x>=xmin]-fcdf_norm)
        pylab.vlines(q[D_location], xcdf[x>=xmin][D_location],
                     fcdf_norm[D_location], color='m', linewidth=2, zorder=2)
        pylab.plot([q[D_location]]*2,
                   [xcdf[x>=xmin][D_location], fcdf_norm[D_location]],
                   color='m',
                   marker='s', zorder=3)

        #plotx = pylab.linspace(q.min(),q.max(),1000)
        #ploty = (plotx/xmin)**(1-alpha) * nc

        if dolog:
            pylab.loglog(x,xcdf,marker=pointmarker,color=pointcolor,**kwargs)
            pylab.loglog(q,fcdf_norm,'r',**kwargs)
        else:
            pylab.semilogx(x,xcdf,marker=pointmarker,color=pointcolor,**kwargs)
            pylab.semilogx(q,fcdf_norm,'r',**kwargs)

        if zoom:
            pylab.axis([xmin, x.max(), xcdf.min(), nc])

Response: Plot CDF and powerlaw of the current object.


Instruction:
Write a Python 3 function for
plotting PDF of the current state of the object.

Response:
def plotpdf(self, x=None, xmin=None, alpha=None, nbins=50, dolog=True,
                dnds=False, drawstyle='steps-post', histcolor='k', plcolor='r',
                fill=False, dohist=True, **kwargs):
        """
        Plots PDF and powerlaw.

        kwargs is passed to pylab.hist and pylab.plot
        """
        if x is None:
            x=self.data
        if xmin is None:
            xmin=self._xmin
        if alpha is None:
            alpha=self._alpha

        x=np.sort(x)
        #n=len(x)

        pylab.gca().set_xscale('log')
        pylab.gca().set_yscale('log')

        if dnds:
            hb = pylab.histogram(x,bins=np.logspace(log10(min(x)),log10(max(x)),nbins))
            h = hb[0]
            b = hb[1]
            db = hb[1][1:]-hb[1][:-1]
            h = h/db
            if dohist:
                pylab.plot(b[:-1],h,drawstyle=drawstyle,color=histcolor,**kwargs)
            #alpha -= 1
        elif dolog:
            hb = pylab.hist(x, bins=np.logspace(log10(min(x)), log10(max(x)),
                                                nbins), log=True, fill=fill,
                            edgecolor=histcolor, **kwargs)
            alpha -= 1
            h,b=hb[0],hb[1]
            if not dohist:
                for rect in hb[2]:
                    rect.set_visible(False)
        else:
            hb = pylab.hist(x, bins=np.linspace((min(x)), (max(x)), nbins),
                            fill=fill, edgecolor=histcolor, **kwargs)
            h,b=hb[0],hb[1]
            if not dohist:
                for rect in hb[2]:
                    rect.set_visible(False)
        # plotting points are at the center of each bin
        b = (b[1:]+b[:-1])/2.0

        q = x[x>=xmin]
        px = (alpha-1)/xmin * (q/xmin)**(-alpha)

        # Normalize by the median ratio between the histogram and the power-law
        # The normalization is semi-arbitrary; an average is probably just as valid
        plotloc = (b>xmin)*(h>0)
        norm = np.median(h[plotloc] / ((alpha-1)/xmin *
                                       (b[plotloc]/xmin)**(-alpha)))
        px = px*norm

        plotx = pylab.linspace(q.min(),q.max(),1000)
        ploty = (alpha-1)/xmin * (plotx/xmin)**(-alpha) * norm

        #pylab.loglog(q,px,'r',**kwargs)
        pylab.plot(plotx, ploty, color=plcolor, **kwargs)

        axlims = pylab.axis()
        pylab.vlines(xmin, axlims[2], max(px), colors=plcolor,
                     linestyle='dashed')

        if dolog and min(x) <= 0:
            lolim = 0.1
        else:
            lolim = min(x)
        pylab.gca().set_xlim(lolim, max(x))


Instruction:
Can you write a function in Python 3 where it
plots the power - law - predicted value on the Y - axis against the real value.

Response:
def plotppf(self,x=None,xmin=None,alpha=None,dolog=True,**kwargs):
        """
        Plots the power-law-predicted value on the Y-axis against the real
        values along the X-axis.  Can be used as a diagnostic of the fit
        quality.
        """
        if not(xmin): xmin=self._xmin
        if not(alpha): alpha=self._alpha
        if not(x): x=np.sort(self.data[self.data>xmin])
        else: x=np.sort(x[x>xmin])

        # N = M^(-alpha+1)
        # M = N^(1/(-alpha+1))

        m0 = min(x)
        N = (1.0+np.arange(len(x)))[::-1]
        xmodel = m0 * N**(1/(1-alpha)) / max(N)**(1/(1-alpha))

        if dolog:
            pylab.loglog(x,xmodel,'.',**kwargs)
            pylab.gca().set_xlim(min(x),max(x))
            pylab.gca().set_ylim(min(x),max(x))
        else:
            pylab.plot(x,xmodel,'.',**kwargs)
        pylab.plot([min(x),max(x)],[min(x),max(x)],'k--')
        pylab.xlabel("Real Value")
        pylab.ylabel("Power-Law Model Value")


Instruction:
Can you tell what is the following Python 3 function doing
def lognormal(self,doprint=True):
        # N = float(self.data.shape[0])
        # mu = log(self.data).sum() / N
        # sigmasquared = ( ( log(self.data) - mu )**2 ).sum() / N
        # self.lognormal_mu = mu
        # self.lognormal_sigma = np.sqrt(sigmasquared)
        # self.lognormal_likelihood = -N/2. * log(np.pi*2) - N/2. * log(sigmasquared) - 1/(2*sigmasquared) * (( self.data - mu )**2).sum()
        # if doprint:
        #     print "Best fit lognormal is exp( -(x-%g)^2 / (2*%g^2)" % (mu,np.sqrt(sigmasquared))
        #     print "Likelihood: %g" % (self.lognormal_likelihood)
        if scipyOK:
            fitpars = scipy.stats.lognorm.fit(self.data)
            self.lognormal_dist = scipy.stats.lognorm(*fitpars)
            self.lognormal_ksD,self.lognormal_ksP = scipy.stats.kstest(self.data,self.lognormal_dist.cdf)
            # nnlf = NEGATIVE log likelihood
            self.lognormal_likelihood = -1*scipy.stats.lognorm.nnlf(fitpars,self.data)

            # Is this the right likelihood ratio?
            # Definition of L from eqn. B3 of Clauset et al 2009:
            # L = log(p(x|alpha))
            # _nnlf from scipy.stats.distributions:
            # -sum(log(self._pdf(x, *args)),axis=0)
            # Assuming the pdf and p(x|alpha) are both non-inverted, it looks
            # like the _nnlf and L have opposite signs, which would explain the
            # likelihood ratio I've used here:
            self.power_lognorm_likelihood = (self._likelihood + self.lognormal_likelihood)
            # a previous version had 2*(above).  That is the correct form if you want the likelihood ratio
            # statistic "D": http://en.wikipedia.org/wiki/Likelihood-ratio_test
            # The above explanation makes sense, since nnlf is the *negative* log likelihood function:
            ## nnlf  -- negative log likelihood function (to minimize)
            #
            # Assuming we want the ratio between the POSITIVE likelihoods, the D statistic is:
            # D = -2 log( L_power / L_lognormal )
            self.likelihood_ratio_D = -2 * (log(self._likelihood/self.lognormal_likelihood))

            if doprint:
                print("Lognormal KS D: %g  p(D): %g" % (self.lognormal_ksD,self.lognormal_ksP), end=' ')
                print("  Likelihood Ratio Statistic (powerlaw/lognormal): %g" % self.likelihood_ratio_D)
                print("At this point, have a look at Clauset et al 2009 Appendix C: determining sigma(likelihood_ratio)")

Response: Produce the best fit lognormal distribution for a single object.


Instruction:
How would you explain what the following Python 3 function does
def plot_lognormal_pdf(self,**kwargs):
        if not hasattr(self,'lognormal_dist'):
            return

        normalized_pdf = self.lognormal_dist.pdf(self.data)/self.lognormal_dist.pdf(self.data).max()
        minY,maxY = pylab.gca().get_ylim()
        pylab.plot(self.data,normalized_pdf*maxY,'.',**kwargs)

Response: Plot the fitted lognormal distribution of the current object.


Instruction:
Here you have a function in Python 3, explain what it does
def plot_lognormal_cdf(self,**kwargs):
        if not hasattr(self,'lognormal_dist'):
            return

        x=np.sort(self.data)
        n=len(x)
        xcdf = np.arange(n,0,-1,dtype='float')/float(n)
        lcdf = self.lognormal_dist.sf(x)

        D_location = argmax(xcdf-lcdf)
        pylab.vlines(x[D_location],xcdf[D_location],lcdf[D_location],color='m',linewidth=2)

        pylab.plot(x, lcdf,',',**kwargs)

Response: Plot the fitted lognormal distribution of the current object.


Instruction:
Can you tell what is the following Python 3 function doing
def sanitize_turbo(html, allowed_tags=TURBO_ALLOWED_TAGS, allowed_attrs=TURBO_ALLOWED_ATTRS):
    return clean(html, tags=allowed_tags, attributes=allowed_attrs, strip=True)

Response: Sanitize HTML removing not allowed tags and attributes.


Instruction:
Given the following Python 3 function, write the documentation
def configure_analytics_yandex(self, ident, params=None):
        params = params or {}

        data = {
            'type': 'Yandex',
            'id': ident,
        }

        if params:
            data['params'] = '%s' % params

        self.analytics.append(data)

Response: Configure Yandex Metrika analytics counter.


Instruction:
How would you explain what the following Python 3 function does
def tag_list(self, tags):
        return [
            (tag.name, "selected taggit-tag" if tag.name in tags else "taggit-tag")
            for tag in self.model.objects.all()
        ]

Response: Generates a list of tags identifying those previously submitted.


Instruction:
How would you explain what the following Python 3 function does
def gcd(self, lon1, lat1, lon2, lat2):
        # convert decimal degrees to radians
        lon1, lat1, lon2, lat2 = map(math.radians, [lon1, lat1, lon2, lat2])

        # haversine formula
        dlon = lon2 - lon1
        dlat = lat2 - lat1
        a = math.sin(dlat / 2) ** 2 + math.cos(lat1) * math.cos(lat2) * math.sin(dlon / 2) ** 2
        c = 2 * math.asin(math.sqrt(a))

        dis = E.R * c
        return dis

Response: Calculate the great circle distance between two points lon1 lat1 lon2 lat2


Instruction:
Write a Python 3 function that can
calculate md5 fingerprint. Shamelessly copied from http://stackoverflow. com/questions / 66682815 / deriving - an - ssh - fingerprint - from - a - public - key - in - python For specification 4. 1. 1

Response:
def hash_md5(self):
        """Calculate md5 fingerprint.

        Shamelessly copied from http://stackoverflow.com/questions/6682815/deriving-an-ssh-fingerprint-from-a-public-key-in-python

        For specification, see RFC4716, section 4."""
        fp_plain = hashlib.md5(self._decoded_key).hexdigest()
        return "MD5:" + ':'.join(a + b for a, b in zip(fp_plain[::2], fp_plain[1::2]))


Instruction:
Can you write a function in Python 3 where it
unpacks the next data field from the given byte stream. Returns a tuple with ( location of next data field contents of requested data field.

Response:
def _unpack_by_int(self, data, current_position):
        """Returns a tuple with (location of next data field, contents of requested data field)."""
        # Unpack length of data field
        try:
            requested_data_length = struct.unpack('>I', data[current_position:current_position + self.INT_LEN])[0]
        except struct.error:
            raise MalformedDataError("Unable to unpack %s bytes from the data" % self.INT_LEN)

        # Move pointer to the beginning of the data field
        current_position += self.INT_LEN
        remaining_data_length = len(data[current_position:])

        if remaining_data_length < requested_data_length:
            raise MalformedDataError(
                "Requested %s bytes, but only %s bytes available." % (requested_data_length, remaining_data_length)
            )

        next_data = data[current_position:current_position + requested_data_length]
        # Move pointer to the end of the data field
        current_position += requested_data_length
        return current_position, next_data


Instruction:
Given the following Python 3 function, write the documentation
def _parse_long(cls, data):
        if sys.version < '3':
            # this does not exist in python 3 - undefined-variable disabled to make pylint happier.
            ret = long(0)  # pylint:disable=undefined-variable
            for byte in data:
                ret = (ret << 8) + ord(byte)
        else:
            ret = 0
            for byte in data:
                ret = (ret << 8) + byte
        return ret

Response: Calculate two s complement.


Instruction:
Can you create a Python 3 function that
decodes base64 coded part of the key.

Response:
def decode_key(cls, pubkey_content):
        """Decode base64 coded part of the key."""
        try:
            decoded_key = base64.b64decode(pubkey_content.encode("ascii"))
        except (TypeError, binascii.Error):
            raise MalformedDataError("Unable to decode the key")
        return decoded_key


Instruction:
Given the following Python 3 function, write the documentation
def parse_options(self, options):
        quote_open = False
        parsed_options = {}

        def parse_add_single_option(opt):
            """Parses and validates a single option, and adds it to parsed_options field."""
            if "=" in opt:
                opt_name, opt_value = opt.split("=", 1)
                opt_value = opt_value.replace('"', '')
            else:
                opt_name = opt
                opt_value = True
            if " " in opt_name or not self.OPTION_NAME_RE.match(opt_name):
                raise InvalidOptionNameError("%s is not valid option name." % opt_name)
            if self.strict_mode:
                for valid_opt_name, value_required in self.OPTIONS_SPEC:
                    if opt_name.lower() == valid_opt_name:
                        if value_required and opt_value is True:
                            raise MissingMandatoryOptionValueError("%s is missing mandatory value." % opt_name)
                        break
                else:
                    raise UnknownOptionNameError("%s is unrecognized option name." % opt_name)
            if opt_name not in parsed_options:
                parsed_options[opt_name] = []
            parsed_options[opt_name].append(opt_value)

        start_of_current_opt = 0
        i = 1  # Need to be set for empty options strings
        for i, character in enumerate(options):
            if character == '"':  # only double quotes are allowed, no need to care about single quotes
                quote_open = not quote_open
            if quote_open:
                continue
            if character == ",":
                opt = options[start_of_current_opt:i]
                parse_add_single_option(opt)
                start_of_current_opt = i + 1
                # Data begins after the first space
        if start_of_current_opt + 1 != i:
            opt = options[start_of_current_opt:]
            parse_add_single_option(opt)
        if quote_open:
            raise InvalidOptionsError("Unbalanced quotes.")
        return parsed_options

Response: Parses the ssh options string and returns a dictionary of parsed ssh options.


Instruction:
Implement a function in Python 3 to
parse ssh - rsa public keys.

Response:
def _process_ssh_rsa(self, data):
        """Parses ssh-rsa public keys."""
        current_position, raw_e = self._unpack_by_int(data, 0)
        current_position, raw_n = self._unpack_by_int(data, current_position)

        unpacked_e = self._parse_long(raw_e)
        unpacked_n = self._parse_long(raw_n)

        self.rsa = RSAPublicNumbers(unpacked_e, unpacked_n).public_key(default_backend())
        self.bits = self.rsa.key_size

        if self.strict_mode:
            min_length = self.RSA_MIN_LENGTH_STRICT
            max_length = self.RSA_MAX_LENGTH_STRICT
        else:
            min_length = self.RSA_MIN_LENGTH_LOOSE
            max_length = self.RSA_MAX_LENGTH_LOOSE
        if self.bits < min_length:
            raise TooShortKeyError(
                "%s key data can not be shorter than %s bits (was %s)" % (self.key_type, min_length, self.bits)
            )
        if self.bits > max_length:
            raise TooLongKeyError(
                "%s key data can not be longer than %s bits (was %s)" % (self.key_type, max_length, self.bits)
            )
        return current_position


Instruction:
Can you implement a function in Python 3 that
parses the ssh - dss public keys.

Response:
def _process_ssh_dss(self, data):
        """Parses ssh-dsa public keys."""
        data_fields = {}
        current_position = 0
        for item in ("p", "q", "g", "y"):
            current_position, value = self._unpack_by_int(data, current_position)
            data_fields[item] = self._parse_long(value)

        q_bits = self._bits_in_number(data_fields["q"])
        p_bits = self._bits_in_number(data_fields["p"])
        if q_bits != self.DSA_N_LENGTH:
            raise InvalidKeyError("Incorrect DSA key parameters: bits(p)=%s, q=%s" % (self.bits, q_bits))
        if self.strict_mode:
            min_length = self.DSA_MIN_LENGTH_STRICT
            max_length = self.DSA_MAX_LENGTH_STRICT
        else:
            min_length = self.DSA_MIN_LENGTH_LOOSE
            max_length = self.DSA_MAX_LENGTH_LOOSE
        if p_bits < min_length:
            raise TooShortKeyError("%s key can not be shorter than %s bits (was %s)" % (self.key_type, min_length, p_bits))
        if p_bits > max_length:
            raise TooLongKeyError(
                "%s key data can not be longer than %s bits (was %s)" % (self.key_type, max_length, p_bits)
            )

        dsa_parameters = DSAParameterNumbers(data_fields["p"], data_fields["q"], data_fields["g"])
        self.dsa = DSAPublicNumbers(data_fields["y"], dsa_parameters).public_key(default_backend())
        self.bits = self.dsa.key_size

        return current_position


Instruction:
Can you write a function in Python 3 where it
parses the ecdsa - sha public keys.

Response:
def _process_ecdsa_sha(self, data):
        """Parses ecdsa-sha public keys."""
        current_position, curve_information = self._unpack_by_int(data, 0)
        if curve_information not in self.ECDSA_CURVE_DATA:
            raise NotImplementedError("Invalid curve type: %s" % curve_information)
        curve, hash_algorithm = self.ECDSA_CURVE_DATA[curve_information]

        current_position, key_data = self._unpack_by_int(data, current_position)
        try:
            # data starts with \x04, which should be discarded.
            ecdsa_key = ecdsa.VerifyingKey.from_string(key_data[1:], curve, hash_algorithm)
        except AssertionError:
            raise InvalidKeyError("Invalid ecdsa key")
        self.bits = int(curve_information.replace(b"nistp", b""))
        self.ecdsa = ecdsa_key
        return current_position


Instruction:
Write a Python 3 script for
parsing ed25516 keys. This only validates the current bit length and returns the current bit position.

Response:
def _process_ed25516(self, data):
        """Parses ed25516 keys.

        There is no (apparent) way to validate ed25519 keys. This only
        checks data length (256 bits), but does not try to validate
        the key in any way."""

        current_position, verifying_key = self._unpack_by_int(data, 0)
        verifying_key_length = len(verifying_key) * 8
        verifying_key = self._parse_long(verifying_key)

        if verifying_key < 0:
            raise InvalidKeyError("ed25519 verifying key must be >0.")

        self.bits = verifying_key_length
        if self.bits != 256:
            raise InvalidKeyLengthError("ed25519 keys must be 256 bits (was %s bits)" % self.bits)
        return current_position


Instruction:
Make a summary of the following Python 3 code
def parse(self, keydata=None):
        if keydata is None:
            if self.keydata is None:
                raise ValueError("Key data must be supplied either in constructor or to parse()")
            keydata = self.keydata
        else:
            self.reset()
            self.keydata = keydata

        if keydata.startswith("---- BEGIN SSH2 PUBLIC KEY ----"):
            # SSH2 key format
            key_type = None  # There is no redundant key-type field - skip comparing plain-text and encoded data.
            pubkey_content = "".join([line for line in keydata.split("\n") if ":" not in line and "----" not in line])
        else:
            key_parts = self._split_key(keydata)
            key_type = key_parts[0]
            pubkey_content = key_parts[1]

        self._decoded_key = self.decode_key(pubkey_content)

        # Check key type
        current_position, unpacked_key_type = self._unpack_by_int(self._decoded_key, 0)
        if key_type is not None and key_type != unpacked_key_type.decode():
            raise InvalidTypeError("Keytype mismatch: %s != %s" % (key_type, unpacked_key_type))

        self.key_type = unpacked_key_type

        key_data_length = self._process_key(self._decoded_key[current_position:])
        current_position = current_position + key_data_length

        if current_position != len(self._decoded_key):
            raise MalformedDataError("Leftover data: %s bytes" % (len(self._decoded_key) - current_position))

        if self.disallow_options and self.options:
            raise InvalidOptionsError("Options are disallowed.")

Response: Validates SSH public key. Returns None if invalid.


Instruction:
Can you write a function in Python 3 where it
creates a list of strings describing the status codes of a single GSSAPI message.

Response:
def status_list(maj_status, min_status, status_type=C.GSS_C_GSS_CODE, mech_type=C.GSS_C_NO_OID):
    """
    Creates a "friendly" error message from a GSS status code. This is used to create the
    :attr:`GSSCException.message` of a :class:`GSSCException`.

    :param maj_status: The major status reported by the C GSSAPI.
    :type maj_status: int
    :param min_status: The minor status reported by the C GSSAPI.
    :type min_status: int
    :param status_type: Whether the status is a general GSSAPI status or a mechanism status.
    :type status_type: ``GSS_C_GSS_CODE`` or ``GSS_C_MECH_CODE``
    :param mech_type: Optional mechanism type, if the status is a mechanism status.
    :type mech_type: :class:`~gssapi.oids.OID`
    :returns: a list of strings describing the error.
    :rtype: list of strings
    """
    from .oids import OID

    statuses = []
    message_context = ffi.new('OM_uint32[1]')
    minor_status = ffi.new('OM_uint32[1]')

    if isinstance(mech_type, OID):
        mech_type = ffi.addressof(mech_type._oid)  # OID._oid is type "struct gss_OID_desc"
    elif mech_type == C.GSS_C_NO_OID:
        mech_type = ffi.cast('gss_OID', C.GSS_C_NO_OID)
    elif not isinstance(mech_type, ffi.CData) or ffi.typeof(mech_type) != ffi.typeof('gss_OID'):
        raise TypeError(
            "Expected mech_type to be a gssapi.oids.OID or gss_OID, got {0}".format(type(mech_type))
        )

    while True:
        status_buf = ffi.new('gss_buffer_desc[1]')

        try:
            retval = C.gss_display_status(
                minor_status,
                maj_status,
                status_type,
                mech_type,
                message_context,
                status_buf
            )
            if retval == C.GSS_S_COMPLETE:
                statuses.append("({0}) {1}.".format(
                    maj_status,
                    _buf_to_str(status_buf[0]).decode("utf-8", errors="replace")
                ))
            elif retval == C.GSS_S_BAD_MECH:
                statuses.append("Unsupported mechanism type passed to GSSException")
                break
            elif retval == C.GSS_S_BAD_STATUS:
                statuses.append("Unrecognized status value passed to GSSException")
                break
        finally:
            C.gss_release_buffer(minor_status, status_buf)

        if message_context[0] == 0:
            break

    if min_status:
        minor_status_msgs = status_list(min_status, 0, C.GSS_C_MECH_CODE, mech_type)
        if minor_status_msgs:
            statuses.append("Minor code:")
            statuses.extend(minor_status_msgs)
    return statuses


Instruction:
Create a Python 3 function to
create a canonical name based on this internal name.

Response:
def canonicalize(self, mech):
        """
        Create a canonical mechanism name (MechName) from an arbitrary internal name. The canonical
        MechName would be set as the :attr:`~gssapi.ctx.AcceptContext.peer_name` property on an
        acceptor's :class:`~gssapi.ctx.AcceptContext` if an initiator performed a successful
        authentication to the acceptor using the given mechanism, using a
        :class:`~gssapi.creds.Credential` obtained using this :class:`Name`.

        :param mech: The mechanism to canonicalize this name for
        :type mech: :class:`~gssapi.oids.OID`
        :returns: a canonical mechanism name based on this internal name.
        :rtype: :class:`MechName`
        """
        if isinstance(mech, OID):
            oid = mech._oid
        else:
            raise TypeError("Expected an OID, got " + str(type(mech)))

        minor_status = ffi.new('OM_uint32[1]')
        out_name = ffi.new('gss_name_t[1]')
        try:
            retval = C.gss_canonicalize_name(
                minor_status, self._name[0], ffi.addressof(oid), out_name
            )
            if GSS_ERROR(retval):
                raise _exception_for_status(retval, minor_status[0])
            return MechName(out_name, mech)
        except:
            C.gss_release_name(minor_status, out_name)


Instruction:
Given the following Python 3 function, write the documentation
def export(self):
        minor_status = ffi.new('OM_uint32[1]')
        output_buffer = ffi.new('gss_buffer_desc[1]')
        retval = C.gss_export_name(
            minor_status,
            self._name[0],
            output_buffer
        )
        try:
            if GSS_ERROR(retval):
                if minor_status[0] and self._mech_type:
                    raise _exception_for_status(retval, minor_status[0], self._mech_type)
                else:
                    raise _exception_for_status(retval, minor_status[0])

            return _buf_to_str(output_buffer[0])
        finally:
            if output_buffer[0].length != 0:
                C.gss_release_buffer(minor_status, output_buffer)

Response: Returns a string representation of this Mechanism Name which can be used for direct comparison against other Mechanism Names.


Instruction:
Can you create a Python 3 function that
returns True if integrity protection has been negotiated in this context False otherwise.

Response:
def integrity_negotiated(self):
        """
        After :meth:`step` has been called, this property will be set to
        True if integrity protection (signing) has been negotiated in this context, False
        otherwise. If this property is True, you can use :meth:`get_mic` to sign messages with a
        message integrity code (MIC), which the peer application can verify.
        """
        return (
            self.flags & C.GSS_C_INTEG_FLAG
        ) and (
            self.established or (self.flags & C.GSS_C_PROT_READY_FLAG)
        )


Instruction:
Here you have a function in Python 3, explain what it does
def confidentiality_negotiated(self):
        return (
            self.flags & C.GSS_C_CONF_FLAG
        ) and (
            self.established or (self.flags & C.GSS_C_PROT_READY_FLAG)
        )

Response: Returns True if confidentiality negotiated in this context False otherwise.


Instruction:
Can you write a function in Python 3 where it
returns True if the security context can use replay detection for messages protected by the current user.

Response:
def replay_detection_negotiated(self):
        """
        After :meth:`step` has been called, this property will be set to
        True if the security context can use replay detection for messages protected by
        :meth:`get_mic` and :meth:`wrap`. False if replay detection cannot be used.
        """
        return (
            self.flags & C.GSS_C_REPLAY_FLAG
        ) and (
            self.established or (self.flags & C.GSS_C_PROT_READY_FLAG)
        )


Instruction:
Explain what the following Python 3 code does
def sequence_detection_negotiated(self):
        return (
            self.flags & C.GSS_C_SEQUENCE_FLAG
        ) and (
            self.established or (self.flags & C.GSS_C_PROT_READY_FLAG)
        )

Response: Returns True if the security context is in sequence or OOS detection mode.


Instruction:
Can you generate the documentation for the following Python 3 function
def get_mic(self, message, qop_req=C.GSS_C_QOP_DEFAULT):
        if not (self.flags & C.GSS_C_INTEG_FLAG):
            raise GSSException("No integrity protection negotiated.")
        if not (self.established or (self.flags & C.GSS_C_PROT_READY_FLAG)):
            raise GSSException("Protection not yet ready.")

        minor_status = ffi.new('OM_uint32[1]')
        output_token_buffer = ffi.new('gss_buffer_desc[1]')
        message_buffer = ffi.new('gss_buffer_desc[1]')
        message_buffer[0].length = len(message)
        c_str_message = ffi.new('char[]', message)
        message_buffer[0].value = c_str_message
        retval = C.gss_get_mic(
            minor_status,
            self._ctx[0],
            ffi.cast('gss_qop_t', qop_req),
            message_buffer,
            output_token_buffer
        )
        try:
            if GSS_ERROR(retval):
                if minor_status[0] and self.mech_type:
                    raise _exception_for_status(retval, minor_status[0], self.mech_type)
                else:
                    raise _exception_for_status(retval, minor_status[0])

            output_token = _buf_to_str(output_token_buffer[0])
            return output_token
        finally:
            if output_token_buffer[0].length != 0:
                C.gss_release_buffer(minor_status, output_token_buffer)

Response: Calculates a MIC over an application message and returns the MIC in a token.


Instruction:
Here you have a function in Python 3, explain what it does
def verify_mic(self, message, mic, supplementary=False):
        if not (self.flags & C.GSS_C_INTEG_FLAG):
            raise GSSException("No integrity protection negotiated.")
        if not (self.established or (self.flags & C.GSS_C_PROT_READY_FLAG)):
            raise GSSException("Protection not yet ready.")

        minor_status = ffi.new('OM_uint32[1]')
        message_buffer = ffi.new('gss_buffer_desc[1]')
        message_buffer[0].length = len(message)
        c_str_message = ffi.new('char[]', message)
        message_buffer[0].value = c_str_message
        mic_buffer = ffi.new('gss_buffer_desc[1]')
        mic_buffer[0].length = len(mic)
        c_str_mic = ffi.new('char[]', mic)
        mic_buffer[0].value = c_str_mic
        qop_state = ffi.new('gss_qop_t[1]')

        retval = C.gss_verify_mic(
            minor_status,
            self._ctx[0],
            message_buffer,
            mic_buffer,
            qop_state
        )
        if GSS_ERROR(retval):
            if minor_status[0] and self.mech_type:
                raise _exception_for_status(retval, minor_status[0], self.mech_type)
            else:
                raise _exception_for_status(retval, minor_status[0])
        supp_bits = _status_bits(retval)
        if supplementary:
            return qop_state[0], supp_bits
        elif len(supp_bits) > 0:
            # Raise if unseq/replayed token detected
            raise _exception_for_status(retval, minor_status[0])
        else:
            return qop_state[0]

Response: This method verifies that the message is valid for the given MIC.


Instruction:
Can you implement a function in Python 3 that
wraps a message with a message integrity code and returns a byte array that can be used to encrypt the MIC.

Response:
def wrap(self, message, conf_req=True, qop_req=C.GSS_C_QOP_DEFAULT):
        """
        Wraps a message with a message integrity code, and if `conf_req` is True, encrypts the
        message. The message can be decrypted and the MIC verified by the peer by passing the
        token returned from this method to :meth:`unwrap` on the peer's side.

        :param message: The message to wrap
        :type message: bytes
        :param conf_req: Whether to require confidentiality (encryption)
        :type conf_req: bool
        :param qop_req: The quality of protection required. It is recommended to not change this
            from the default as most GSSAPI implementations do not support it.
        :returns: the wrapped message in a token suitable for passing to :meth:`unwrap`
        :rtype: bytes
        :raises: GSSException if integrity protection is not available
            (:attr:`integrity_negotiated` is False), or if the `conf_req` parameter is True and
            confidentiality protection is not available
            (:attr:`confidentiality_negotiated` is False)
        """
        if not (self.flags & C.GSS_C_INTEG_FLAG):
            raise GSSException("No integrity protection negotiated.")
        if (conf_req and not (self.flags & C.GSS_C_CONF_FLAG)):
            raise GSSException("No confidentiality protection negotiated.")
        if not (self.established or (self.flags & C.GSS_C_PROT_READY_FLAG)):
            raise GSSException("Protection not yet ready.")

        minor_status = ffi.new('OM_uint32[1]')
        output_token_buffer = ffi.new('gss_buffer_desc[1]')
        message_buffer = ffi.new('gss_buffer_desc[1]')
        message_buffer[0].length = len(message)
        c_str_message = ffi.new('char[]', message)
        message_buffer[0].value = c_str_message
        conf_state = ffi.new('int[1]')

        retval = C.gss_wrap(
            minor_status,
            self._ctx[0],
            ffi.cast('int', conf_req),
            ffi.cast('gss_qop_t', qop_req),
            message_buffer,
            conf_state,
            output_token_buffer
        )
        try:
            if GSS_ERROR(retval):
                if minor_status[0] and self.mech_type:
                    raise _exception_for_status(retval, minor_status[0], self.mech_type)
                else:
                    raise _exception_for_status(retval, minor_status[0])

            output_token = _buf_to_str(output_token_buffer[0])
            if conf_req and not conf_state[0]:
                raise GSSException("No confidentiality protection.")
            return output_token
        finally:
            if output_token_buffer[0].length != 0:
                C.gss_release_buffer(minor_status, output_token_buffer)


Instruction:
Explain what the following Python 3 code does
def unwrap(self, message, conf_req=True, qop_req=None, supplementary=False):
        if not (self.flags & C.GSS_C_INTEG_FLAG):
            raise GSSException("No integrity protection negotiated.")
        if not (self.established or (self.flags & C.GSS_C_PROT_READY_FLAG)):
            raise GSSException("Protection not yet ready.")

        minor_status = ffi.new('OM_uint32[1]')
        output_buffer = ffi.new('gss_buffer_desc[1]')
        message_buffer = ffi.new('gss_buffer_desc[1]')
        message_buffer[0].length = len(message)
        c_str_message = ffi.new('char[]', message)
        message_buffer[0].value = c_str_message
        conf_state = ffi.new('int[1]')
        qop_state = ffi.new('gss_qop_t[1]')

        retval = C.gss_unwrap(
            minor_status,
            self._ctx[0],
            message_buffer,
            output_buffer,
            conf_state,
            qop_state
        )
        try:
            if GSS_ERROR(retval):
                if minor_status[0] and self.mech_type:
                    raise _exception_for_status(retval, minor_status[0], self.mech_type)
                else:
                    raise _exception_for_status(retval, minor_status[0])

            output = _buf_to_str(output_buffer[0])
            if conf_req and not conf_state[0]:
                raise GSSException("No confidentiality protection.")
            if qop_req is not None and qop_req != qop_state[0]:
                raise GSSException("QOP {0} does not match required value {1}.".format(qop_state[0], qop_req))
            supp_bits = _status_bits(retval)
            if supplementary:
                return output, supp_bits
            elif len(supp_bits) > 0:
                # Raise if unseq/replayed token detected
                raise _exception_for_status(retval, minor_status[0], token=output)
            else:
                return output
        finally:
            if output_buffer[0].length != 0:
                C.gss_release_buffer(minor_status, output_buffer)

Response: Unwraps a message with the security context s cryptographic keys.


Instruction:
Implement a Python 3 function for
calculating the maximum size of a wrapped token.

Response:
def get_wrap_size_limit(self, output_size, conf_req=True, qop_req=C.GSS_C_QOP_DEFAULT):
        """
        Calculates the maximum size of message that can be fed to :meth:`wrap` so that the size of
        the resulting wrapped token (message plus wrapping overhead) is no more than a given
        maximum output size.

        :param output_size: The maximum output size (in bytes) of a wrapped token
        :type output_size: int
        :param conf_req: Whether to calculate the wrapping overhead for confidentiality protection
            (if True) or just integrity protection (if False).
        :type conf_req: bool
        :returns: The maximum input size (in bytes) of message that can be passed to :meth:`wrap`
        :rtype: int
        """

        minor_status = ffi.new('OM_uint32[1]')
        max_input_size = ffi.new('OM_uint32[1]')
        retval = C.gss_wrap_size_limit(
            minor_status,
            self._ctx[0],
            ffi.cast('int', conf_req),
            ffi.cast('gss_qop_t', qop_req),
            ffi.cast('OM_uint32', output_size),
            max_input_size
        )
        if GSS_ERROR(retval):
            if minor_status[0] and self.mech_type:
                raise _exception_for_status(retval, minor_status[0], self.mech_type)
            else:
                raise _exception_for_status(retval, minor_status[0])

        return max_input_size[0]


Instruction:
Can you create a Python 3 function that
processes a context token and return a new token.

Response:
def process_context_token(self, context_token):
        """
        Provides a way to pass an asynchronous token to the security context, outside of the normal
        context-establishment token passing flow. This method is not normally used, but some
        example uses are:

        * when the initiator's context is established successfully but the acceptor's context isn't
          and the acceptor needs to signal to the initiator that the context shouldn't be used.
        * if :meth:`delete` on one peer's context returns a final token that can be passed to the
          other peer to indicate the other peer's context should be torn down as well (though it's
          recommended that :meth:`delete` should return nothing, i.e. this method should not be
          used by GSSAPI mechanisms).

        :param context_token: The context token to pass to the security context
        :type context_token: bytes
        :raises: :exc:`~gssapi.error.DefectiveToken` if consistency checks on the token failed.
            :exc:`~gssapi.error.NoContext` if this context is invalid.
            :exc:`~gssapi.error.GSSException` for any other GSSAPI errors.
        """
        minor_status = ffi.new('OM_uint32[1]')
        context_token_buffer = ffi.new('gss_buffer_desc[1]')
        context_token_buffer[0].length = len(context_token)
        c_str_context_token = ffi.new('char[]', context_token)
        context_token_buffer[0].value = c_str_context_token
        retval = C.gss_process_context_token(
            minor_status,
            self._ctx[0],
            context_token_buffer
        )
        if GSS_ERROR(retval):
            if minor_status[0] and self.mech_type:
                raise _exception_for_status(retval, minor_status[0], self.mech_type)
            else:
                raise _exception_for_status(retval, minor_status[0])


Instruction:
Can you tell what is the following Python 3 function doing
def export(self):
        if not (self.flags & C.GSS_C_TRANS_FLAG):
            raise GSSException("Context is not transferable.")
        if not self._ctx:
            raise GSSException("Can't export empty/invalid context.")

        minor_status = ffi.new('OM_uint32[1]')
        output_token_buffer = ffi.new('gss_buffer_desc[1]')
        retval = C.gss_export_sec_context(
            minor_status,
            self._ctx,
            output_token_buffer
        )
        try:
            if GSS_ERROR(retval):
                if minor_status[0] and self.mech_type:
                    raise _exception_for_status(retval, minor_status[0], self.mech_type)
                else:
                    raise _exception_for_status(retval, minor_status[0])

            exported_token = _buf_to_str(output_token_buffer[0])
            # Set our context to a 'blank' context
            self._ctx = ffi.new('gss_ctx_id_t[1]')
            return exported_token
        finally:
            if output_token_buffer[0].length != 0:
                C.gss_release_buffer(minor_status, output_token_buffer)

Response: This method deactivates the security context and returns an interprocess token which is used to create a new interprocess token for the current security context.


Instruction:
Create a Python 3 function to
return the lifetime of the context.

Response:
def lifetime(self):
        """
        The lifetime of the context in seconds (only valid after :meth:`step` has been called). If
        the context does not have a time limit on its validity, this will be
        :const:`gssapi.C_INDEFINITE`
        """

        minor_status = ffi.new('OM_uint32[1]')
        lifetime_rec = ffi.new('OM_uint32[1]')

        retval = C.gss_inquire_context(
            minor_status,
            self._ctx[0],
            ffi.NULL,  # src_name
            ffi.NULL,  # target_name
            lifetime_rec,
            ffi.NULL,  # mech_type
            ffi.NULL,  # ctx_flags
            ffi.NULL,  # locally_initiated
            ffi.NULL   # established
        )
        if GSS_ERROR(retval):
            if minor_status[0] and self.mech_type:
                raise _exception_for_status(retval, minor_status[0], self.mech_type)
            else:
                raise _exception_for_status(retval, minor_status[0])
        return lifetime_rec[0]


Instruction:
Create a Python 3 function for
deleting a security context. This method will delete the local data structures associated with the specified security context, and may return an output token, which when passed to :meth:`process_context_token` on the peer may instruct it to also delete its context. RFC 2744 recommends that GSSAPI mechanisms do not emit any output token when they're deleted, so this behaviour could be considered deprecated. After this method is called, this security context will become invalid and should not be used in any way. :returns: An output token if one was emitted by the GSSAPI mechanism, otherwise an empty bytestring. :rtype: bytes

Response:
def delete(self):
        """
        Delete a security context. This method will delete the local data structures associated
        with the specified security context, and may return an output token, which when passed to
        :meth:`process_context_token` on the peer may instruct it to also delete its context.

        RFC 2744 recommends that GSSAPI mechanisms do not emit any output token when they're
        deleted, so this behaviour could be considered deprecated.

        After this method is called, this security context will become invalid and should not be
        used in any way.

        :returns: An output token if one was emitted by the GSSAPI mechanism, otherwise an empty
            bytestring.
        :rtype: bytes
        """

        if not self._ctx[0]:
            raise GSSException("Can't delete invalid context")
        output_token_buffer = ffi.new('gss_buffer_desc[1]')
        minor_status = ffi.new('OM_uint32[1]')
        retval = C.gss_delete_sec_context(
            minor_status,
            self._ctx,
            output_token_buffer
        )
        self._ctx = ffi.new('gss_ctx_id_t[1]')
        self._reset_flags()
        try:
            if GSS_ERROR(retval):
                if minor_status[0] and self.mech_type:
                    raise _exception_for_status(retval, minor_status[0], self.mech_type)
                else:
                    raise _exception_for_status(retval, minor_status[0])

            return _buf_to_str(output_token_buffer[0])
        finally:
            if output_token_buffer[0].length != 0:
                C.gss_release_buffer(minor_status, output_token_buffer)


Instruction:
Make a summary of the following Python 3 code
def step(self, input_token=None):

        minor_status = ffi.new('OM_uint32[1]')

        if input_token:
            input_token_buffer = ffi.new('gss_buffer_desc[1]')
            input_token_buffer[0].length = len(input_token)
            c_str_input_token = ffi.new('char[]', input_token)
            input_token_buffer[0].value = c_str_input_token
        else:
            input_token_buffer = ffi.cast('gss_buffer_t', C.GSS_C_NO_BUFFER)

        if isinstance(self._desired_mech, OID):
            desired_mech = ffi.addressof(self._desired_mech._oid)
        else:
            desired_mech = ffi.cast('gss_OID', C.GSS_C_NO_OID)

        actual_mech = ffi.new('gss_OID[1]')
        output_token_buffer = ffi.new('gss_buffer_desc[1]')
        actual_flags = ffi.new('OM_uint32[1]')
        actual_time = ffi.new('OM_uint32[1]')

        if self._cred_object is not None:
            cred = self._cred_object._cred[0]
        else:
            cred = ffi.cast('gss_cred_id_t', C.GSS_C_NO_CREDENTIAL)

        retval = C.gss_init_sec_context(
            minor_status,
            cred,
            self._ctx,
            self.peer_name._name[0],
            desired_mech,
            self._req_flags,
            self._time_req,
            self._channel_bindings,
            input_token_buffer,
            actual_mech,
            output_token_buffer,
            actual_flags,
            actual_time
        )
        try:
            if output_token_buffer[0].length != 0:
                out_token = _buf_to_str(output_token_buffer[0])
            else:
                out_token = None

            if GSS_ERROR(retval):
                if minor_status[0] and actual_mech[0]:
                    raise _exception_for_status(retval, minor_status[0], actual_mech[0], out_token)
                else:
                    raise _exception_for_status(retval, minor_status[0], None, out_token)

            self.established = not (retval & C.GSS_S_CONTINUE_NEEDED)
            self.flags = actual_flags[0]

            if actual_mech[0]:
                self.mech_type = OID(actual_mech[0][0])

            return out_token
        except:
            if self._ctx[0]:
                C.gss_delete_sec_context(
                    minor_status,
                    self._ctx,
                    ffi.cast('gss_buffer_t', C.GSS_C_NO_BUFFER)
                )
                self._reset_flags()
            raise
        finally:
            if output_token_buffer[0].length != 0:
                C.gss_release_buffer(minor_status, output_token_buffer)

Response: Performs a step to establish the context as an initiator.


Instruction:
Implement a Python 3 function for
performing a step to establish the context as an acceptor.

Response:
def step(self, input_token):
        """Performs a step to establish the context as an acceptor.

        This method should be called in a loop and fed input tokens from the initiator, and its
        output tokens should be sent to the initiator, until this context's :attr:`established`
        attribute is True.

        :param input_token: The input token from the initiator (required).
        :type input_token: bytes
        :returns: either a byte string with the next token to send to the initiator,
            or None if there is no further token to send to the initiator.
        :raises: :exc:`~gssapi.error.GSSException` if there is an error establishing the context.
        """
        minor_status = ffi.new('OM_uint32[1]')
        input_token_buffer = ffi.new('gss_buffer_desc[1]')
        input_token_buffer[0].length = len(input_token)
        c_str_import_token = ffi.new('char[]', input_token)
        input_token_buffer[0].value = c_str_import_token

        mech_type = ffi.new('gss_OID[1]')
        output_token_buffer = ffi.new('gss_buffer_desc[1]')
        src_name_handle = ffi.new('gss_name_t[1]')
        actual_flags = ffi.new('OM_uint32[1]')
        time_rec = ffi.new('OM_uint32[1]')
        delegated_cred_handle = ffi.new('gss_cred_id_t[1]')

        if self._cred_object is not None:
            cred = self._cred_object._cred[0]
        else:
            cred = ffi.cast('gss_cred_id_t', C.GSS_C_NO_CREDENTIAL)

        retval = C.gss_accept_sec_context(
            minor_status,
            self._ctx,
            cred,
            input_token_buffer,
            self._channel_bindings,
            src_name_handle,
            mech_type,
            output_token_buffer,
            actual_flags,
            time_rec,
            delegated_cred_handle
        )
        if src_name_handle[0]:
            src_name = MechName(src_name_handle, mech_type[0])  # make sure src_name is GC'd
        try:
            if output_token_buffer[0].length != 0:
                out_token = _buf_to_str(output_token_buffer[0])
            else:
                out_token = None

            if GSS_ERROR(retval):
                if minor_status[0] and mech_type[0]:
                    raise _exception_for_status(retval, minor_status[0], mech_type[0], out_token)
                else:
                    raise _exception_for_status(retval, minor_status[0], None, out_token)

            self.established = not (retval & C.GSS_S_CONTINUE_NEEDED)
            self.flags = actual_flags[0]

            if (self.flags & C.GSS_C_DELEG_FLAG):
                self.delegated_cred = Credential(delegated_cred_handle)

            if mech_type[0]:
                self.mech_type = OID(mech_type[0][0])

                if src_name_handle[0]:
                    src_name._mech_type = self.mech_type
                    self.peer_name = src_name

            return out_token
        except:
            if self._ctx:
                C.gss_delete_sec_context(
                    minor_status,
                    self._ctx,
                    ffi.cast('gss_buffer_t', C.GSS_C_NO_BUFFER)
                )
                self._reset_flags()
            raise
        finally:
            if output_token_buffer[0].length != 0:
                C.gss_release_buffer(minor_status, output_token_buffer)
            # if self.delegated_cred is present, it will handle gss_release_cred:
            if delegated_cred_handle[0] and not self.delegated_cred:
                C.gss_release_cred(minor_status, delegated_cred_handle)


Instruction:
Can you tell what is the following Python 3 function doing
def mechs(self):
        if not self._mechs:
            self._mechs = self._inquire(False, False, False, True)[3]
        return self._mechs

Response: Returns a set of mechanisms supported by the credential.


Instruction:
Can you write a function in Python 3 where it
exports this credential into a byte string which can be passed to imprt in order to serialize it into a byte string.

Response:
def export(self):
        """
        Serializes this credential into a byte string, which can be passed to :meth:`imprt` in
        another process in order to deserialize the byte string back into a credential. Exporting
        a credential does not destroy it.

        :returns: The serialized token representation of this credential.
        :rtype: bytes
        :raises: :exc:`~gssapi.error.GSSException` if there is a problem with exporting the
            credential.

            :exc:`NotImplementedError` if the underlying GSSAPI implementation does not
            support the ``gss_export_cred`` C function.
        """
        if not hasattr(C, 'gss_export_cred'):
            raise NotImplementedError("The GSSAPI implementation does not support gss_export_cred")

        minor_status = ffi.new('OM_uint32[1]')
        output_buffer = ffi.new('gss_buffer_desc[1]')
        retval = C.gss_export_cred(minor_status, self._cred[0], output_buffer)
        try:
            if GSS_ERROR(retval):
                raise _exception_for_status(retval, minor_status[0])

            return _buf_to_str(output_buffer[0])
        finally:
            if output_buffer[0].length != 0:
                C.gss_release_buffer(minor_status, output_buffer)


Instruction:
Given the following Python 3 function, write the documentation
def imprt(cls, token):
        if not hasattr(C, 'gss_import_cred'):
            raise NotImplementedError("The GSSAPI implementation does not support gss_import_cred")

        minor_status = ffi.new('OM_uint32[1]')

        token_buffer = ffi.new('gss_buffer_desc[1]')
        token_buffer[0].length = len(token)
        c_str_token = ffi.new('char[]', token)
        token_buffer[0].value = c_str_token

        imported_cred = ffi.new('gss_cred_id_t[1]')

        retval = C.gss_import_cred(minor_status, token_buffer, imported_cred)
        try:
            if GSS_ERROR(retval):
                raise _exception_for_status(retval, minor_status[0])

            return cls(imported_cred)
        except:
            _release_gss_cred_id_t(imported_cred)
            raise

Response: Deserializes a byte string token into a : class:`Credential object.


Instruction:
Given the following Python 3 function, write the documentation
def store(self, usage=None, mech=None, overwrite=False, default=False, cred_store=None):
        if usage is None:
            usage = self.usage
        if isinstance(mech, OID):
            oid_ptr = ffi.addressof(mech._oid)
        else:
            oid_ptr = ffi.cast('gss_OID', C.GSS_C_NO_OID)

        minor_status = ffi.new('OM_uint32[1]')
        elements_stored = ffi.new('gss_OID_set[1]')
        usage_stored = ffi.new('gss_cred_usage_t[1]')

        if cred_store is None:
            if not hasattr(C, 'gss_store_cred'):
                raise NotImplementedError("The GSSAPI implementation does not support "
                                          "gss_store_cred")

            retval = C.gss_store_cred(
                minor_status,
                self._cred[0],
                ffi.cast('gss_cred_usage_t', usage),
                oid_ptr,
                ffi.cast('OM_uint32', overwrite),
                ffi.cast('OM_uint32', default),
                elements_stored,
                usage_stored
            )
        else:
            if not hasattr(C, 'gss_store_cred_into'):
                raise NotImplementedError("The GSSAPI implementation does not support "
                                          "gss_store_cred_into")

            c_strings, elements, cred_store_kv_set = _make_kv_set(cred_store)

            retval = C.gss_store_cred_into(
                minor_status,
                self._cred[0],
                ffi.cast('gss_cred_usage_t', usage),
                oid_ptr,
                ffi.cast('OM_uint32', overwrite),
                ffi.cast('OM_uint32', default),
                cred_store_kv_set,
                elements_stored,
                usage_stored
            )
        try:
            if GSS_ERROR(retval):
                if oid_ptr:
                    raise _exception_for_status(retval, minor_status[0], oid_ptr)
                else:
                    raise _exception_for_status(retval, minor_status[0])
        except:
            if elements_stored[0]:
                C.gss_release_oid_set(minor_status, elements_stored)
            raise

        return (OIDSet(elements_stored), usage_stored[0])

Response: Stores this credential into a credential store.


Instruction:
Given the following Python 3 function, write the documentation
def get_all_mechs():
    minor_status = ffi.new('OM_uint32[1]')
    mech_set = ffi.new('gss_OID_set[1]')
    try:
        retval = C.gss_indicate_mechs(minor_status, mech_set)
        if GSS_ERROR(retval):
            raise _exception_for_status(retval, minor_status[0])
    except:
        _release_OID_set(mech_set)
        raise
    return OIDSet(oid_set=mech_set)

Response:
Return an OIDSet of all the mechanisms supported by the underlying GSSAPI
    implementation.


Instruction:
Create a Python 3 function to
take a string form of a mechanism OID and returns an OID object representing the mechanism.

Response:
def mech_from_string(input_string):
        """
        Takes a string form of a mechanism OID, in dot-separated: "1.2.840.113554.1.2.2" or numeric
        ASN.1: "{1 2 840 113554 1 2 2}" notation, and returns an :class:`OID` object representing
        the mechanism, which can be passed to other GSSAPI methods.

        :param input_string: a string representing the desired mechanism OID.
        :returns: the mechanism OID.
        :rtype: :class:`OID`
        :raises: ValueError if the the input string is ill-formatted.
        :raises: KeyError if the mechanism identified by the string is not supported by the
            underlying GSSAPI implementation.
        """
        if not re.match(r'^\d+(\.\d+)*$', input_string):
            if re.match(r'^\{\d+( \d+)*\}$', input_string):
                input_string = ".".join(input_string[1:-1].split())
            else:
                raise ValueError(input_string)
        for mech in get_all_mechs():
            if input_string == str(mech):
                return mech
        raise KeyError("Unknown mechanism: {0}".format(input_string))


Instruction:
Implement a function in Python 3 to
return a new set with the OID passed in as the only member of the set.

Response:
def singleton_set(cls, single_oid):
        """
        Factory function to create a new :class:`OIDSet` with a single member.

        :param single_oid: the OID to use as a member of the new set
        :type single_oid: :class:`OID`
        :returns: an OID set with the OID passed in as the only member
        :rtype: :class:`OIDSet`
        """
        new_set = cls()
        oid_ptr = None
        if isinstance(single_oid, OID):
            oid_ptr = ffi.addressof(single_oid._oid)
        elif isinstance(single_oid, ffi.CData):
            if ffi.typeof(single_oid) == ffi.typeof('gss_OID_desc'):
                oid_ptr = ffi.addressof(single_oid)
            elif ffi.typeof(single_oid) == ffi.typeof('gss_OID'):
                oid_ptr = single_oid
        if oid_ptr is None:
            raise TypeError("Expected a gssapi.oids.OID, got " + str(type(single_oid)))

        minor_status = ffi.new('OM_uint32[1]')
        retval = C.gss_add_oid_set_member(minor_status, oid_ptr, new_set._oid_set)
        if GSS_ERROR(retval):
            raise _exception_for_status(retval, minor_status[0])
        return new_set


Instruction:
Write a Python 3 function that can
add a new entry to the set.

Response:
def add(self, new_oid):
        """
        Adds another :class:`OID` to this set.

        :param new_oid: the OID to add.
        :type new_oid: :class:`OID`
        """
        if self._oid_set[0]:
            oid_ptr = None
            if isinstance(new_oid, OID):
                oid_ptr = ffi.addressof(new_oid._oid)
            elif isinstance(new_oid, ffi.CData):
                if ffi.typeof(new_oid) == ffi.typeof('gss_OID_desc'):
                    oid_ptr = ffi.addressof(new_oid)
                elif ffi.typeof(new_oid) == ffi.typeof('gss_OID'):
                    oid_ptr = new_oid
            if oid_ptr is None:
                raise TypeError("Expected a gssapi.oids.OID, got " + str(type(new_oid)))

            minor_status = ffi.new('OM_uint32[1]')
            retval = C.gss_add_oid_set_member(minor_status, oid_ptr, self._oid_set)
            if GSS_ERROR(retval):
                raise _exception_for_status(retval, minor_status[0])
        else:
            raise GSSException("Cannot add a member to this OIDSet, its gss_OID_set is NULL!")


Instruction:
Given the following Python 3 function, write the documentation
def main(properties=properties, options=options, **custom_options):
    return init(**dict(options, **custom_options))(**properties)

Response: Imports and runs setup function with given properties.


Instruction:
Create a Python 3 function for
importing and returns a setup function.

Response:
def init(
    dist='dist',
    minver=None,
    maxver=None,
    use_markdown_readme=True,
    use_stdeb=False,
    use_distribute=False,
    ):
    """Imports and returns a setup function.

    If use_markdown_readme is set,
    then README.md is added to setuptools READMES list.

    If use_stdeb is set on a Debian based system,
    then module stdeb is imported.
    Stdeb supports building deb packages on Debian based systems.
    The package should only be installed on the same system version
    it was built on, though. See http://github.com/astraw/stdeb.

    If use_distribute is set, then distribute_setup.py is imported.
    """
    if not minver == maxver == None:
        import sys
        if not minver <= sys.version < (maxver or 'Any'):
            sys.stderr.write(
                '%s: requires python version in <%s, %s), not %s\n' % (
                sys.argv[0], minver or 'any', maxver or 'any', sys.version.split()[0]))
            sys.exit(1)

    if use_distribute:
        from distribute_setup import use_setuptools
        use_setuptools(to_dir=dist)
        from setuptools import setup
    else:
        try:
            from setuptools import setup
        except ImportError:
            from distutils.core import setup

    if use_markdown_readme:
        try:
            import setuptools.command.sdist
            setuptools.command.sdist.READMES = tuple(list(getattr(setuptools.command.sdist, 'READMES', ()))
                + ['README.md'])
        except ImportError:
            pass

    if use_stdeb:
        import platform
        if 'debian' in platform.dist():
            try:
                import stdeb
            except ImportError:
                pass

    return setup


Instruction:
Given the following Python 3 function, write the documentation
def main(context=None, *args, **kwargs):

    # Get configuration
    args = _get_command_line_args()
    # Get settings filepath
    settings_filepath = args.get('settings_path')
    # Get settings using the settings filepath
    settings = _get_settings(settings_filepath)
    settings = settings.get('microphone', {})
    # TODO: verify that this doesn't break things in new and interesting ways
    settings.update(kwargs)

    plugin_manager = pluginmanager.PluginInterface()
    plugin_manager.set_entry_points('microphone.audioengines')
    plugins = plugin_manager.collect_entry_point_plugins(return_dict=True)

    # find the audio driver or stick to the default of `pyaudio`
    audio_driver = settings.get('audio_driver', 'pyaudio')

    try:
        # NOTE: `AudioDriver` is a class
        AudioDriver = plugins[audio_driver]
    # Fail early if we can't find the plugin we're looking for
    except KeyError:
        logging.error('Audio driver set in microphone settings of {} not foun'
                      'd. Please install or fix your settings file.')

        logging.error('Plugins available: {}'.format(list(plugins.keys())))
        sys.exit(1)

    # TODO: Assume that a computer will only use one audio driver?

    # Also assume that microphones may be physcially displaced from each other
    # which means that they might record simultaneously

    # FIXME: these are not good default addresses
    command_publish_address = settings.get('publish_address',
                                           'tcp://127.0.0.1:6910')

    command_subscribe_address = settings.get('subscribe_address',
                                             'tcp://127.0.0.1:6823')

    audio_publish_address = settings.get('audio_publish_address',
                                         'tcp://127.0.0.1:5012')

    messaging = Messaging(command_publish_address,
                          command_subscribe_address,
                          audio_publish_address)

    audio_driver = AudioDriver(messaging, settings)

    audio_driver.run()

Response: Main function for the microphone command line tool.


Instruction:
How would you code a function in Python 3 to
create a file handle which is used to record audio

Response:
def _create_file():
    """
    Returns a file handle which is used to record audio
    """
    f = wave.open('audio.wav', mode='wb')
    f.setnchannels(2)
    p = pyaudio.PyAudio()
    f.setsampwidth(p.get_sample_size(pyaudio.paInt16))
    f.setframerate(p.get_default_input_device_info()['defaultSampleRate'])
    try:
        yield f
    finally:
        f.close()


Instruction:
Implement a function in Python 3 to
get all PyAudio devices.

Response:
def get_devices(self, device_type='all'):
        num_devices = self._pyaudio.get_device_count()
        self._logger.debug('Found %d PyAudio devices', num_devices)
        for i in range(num_devices):
            info = self._pyaudio.get_device_info_by_index(i)
            name = info['name']
            if name in self.devices:
                continue
            else:
                self.devices[name] = PyAudioDevice(self, info)

        return self.devices
        """
        if device_type == plugin.audioengine.DEVICE_TYPE_ALL:
            return devs
        else:
            return [device for device in devs if device_type in device.types]
        """


Instruction:
Can you generate the documentation for the following Python 3 function
def open_stream(self,
                    bits,
                    channels,
                    rate=None,
                    chunksize=1024,
                    output=True):

        if rate is None:
            rate = int(self.info['defaultSampleRate'])
        # Check if format is supported
        is_supported_fmt = self.supports_format(bits, channels, rate,
                                                output=output)
        if not is_supported_fmt:
            msg_fmt = ("PyAudioDevice {index} ({name}) doesn't support " +
                       "%s format (Int{bits}, {channels}-channel at" +
                       " {rate} Hz)") % ('output' if output else 'input')
            msg = msg_fmt.format(index=self.index,
                                 name=self.name,
                                 bits=bits,
                                 channels=channels,
                                 rate=rate)
            self._logger.critical(msg)
            raise plugin.audioengine.UnsupportedFormat(msg)
        # Everything looks fine, open the stream
        direction = ('output' if output else 'input')
        stream_kwargs = {
            'format': bits_to_samplefmt(bits),
            'channels': channels,
            'rate': rate,
            'output': output,
            'input': not output,
            ('%s_device_index' % direction): self._index,
            'frames_per_buffer': chunksize if output else chunksize*8  # Hacky
        }

        stream = self._engine._pyaudio.open(**stream_kwargs)
        """
        self._logger.debug("%s stream opened on device '%s' (%d Hz, %d " +
                           "channel, %d bit)", "output" if output else "input",
                           self.slug, rate, channels, bits)
        """
        try:
            yield stream
        finally:
            stream.close()
            """
            self._logger.debug("%s stream closed on device '%s'",
                               "output" if output else "input", self.slug)
            """

Response: Open a stream of the next available state.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def djfrontend_h5bp_css(version=None):
    if version is None:
        version = getattr(settings, 'DJFRONTEND_H5BP_CSS', DJFRONTEND_H5BP_CSS_DEFAULT)

    return format_html(
        '<link rel="stylesheet" href="{0}djfrontend/css/h5bp/{1}/h5bp.css">',
        _static_url, version)

Response: Returns the HTML5 Boilerplate CSS file.


Instruction:
Given the following Python 3 function, write the documentation
def djfrontend_normalize(version=None):
    if version is None:
        version = getattr(settings, 'DJFRONTEND_NORMALIZE', DJFRONTEND_NORMALIZE_DEFAULT)

    return format_html(
        '<link rel="stylesheet" href="{0}djfrontend/css/normalize/{1}/normalize.css">',
        _static_url, version)

Response: Returns a normalized HTML file.


Instruction:
Can you create a Python 3 function that
returns the font - awesome stylesheet.

Response:
def djfrontend_fontawesome(version=None):
    """
    Returns Font Awesome CSS file.
    TEMPLATE_DEBUG returns full file, otherwise returns minified file.
    """
    if version is None:
        version = getattr(settings, 'DJFRONTEND_FONTAWESOME', DJFRONTEND_FONTAWESOME_DEFAULT)

    return format_html(
        '<link rel="stylesheet" href="{0}djfrontend/css/fontawesome/{1}/font-awesome{2}.css">',
        _static_url, version, _min)


Instruction:
Create a Python 3 function to
return Modernizr JavaScript file according to version number.

Response:
def djfrontend_modernizr(version=None):
    """
    Returns Modernizr JavaScript file according to version number.
    TEMPLATE_DEBUG returns full file, otherwise returns minified file.
    Included in HTML5 Boilerplate.
    """
    if version is None:
        version = getattr(settings, 'DJFRONTEND_MODERNIZR', DJFRONTEND_MODERNIZR_DEFAULT)

    if getattr(settings, 'TEMPLATE_DEBUG', False):
        template = '<script src="{static}djfrontend/js/modernizr/{v}/modernizr.js"></script>'
    else:
        template = (
            '<script src="//cdnjs.cloudflare.com/ajax/libs/modernizr/{v}/modernizr.min.js"></script>\n'
            '<script>window.Modernizr || document.write(\'<script src="{static}djfrontend/js/modernizr/{v}/modernizr.min.js"><\/script>\')</script>')
    return format_html(template, static=_static_url, v=version)


Instruction:
Make a summary of the following Python 3 code
def djfrontend_jquery(version=None):
    if version is None:
        version = getattr(settings, 'DJFRONTEND_JQUERY', DJFRONTEND_JQUERY_DEFAULT)

    if getattr(settings, 'TEMPLATE_DEBUG', False):
        template = '<script src="{static}djfrontend/js/jquery/{v}/jquery.js"></script>'
    else:
        template = (
            '<script src="//ajax.googleapis.com/ajax/libs/jquery/{v}/jquery.min.js"></script>'
            '<script>window.jQuery || document.write(\'<script src="{static}djfrontend/js/jquery/{v}/jquery.min.js"><\/script>\')</script>')
    return format_html(template, static=_static_url, v=version)

Response: Returns jQuery JavaScript file according to version number.


Instruction:
Write a Python 3 script for
returning the jQuery UI plugin file according to version number.

Response:
def djfrontend_jqueryui(version=None):
    """
    Returns the jQuery UI plugin file according to version number.
    TEMPLATE_DEBUG returns full file, otherwise returns minified file from Google CDN with local fallback.
    """
    if version is None:
        version = getattr(settings, 'DJFRONTEND_JQUERYUI', DJFRONTEND_JQUERYUI_DEFAULT)

    if getattr(settings, 'TEMPLATE_DEBUG', False):
        return format_html(
            '<script src="{0}djfrontend/js/jquery/jqueryui/{1}/jquery-ui.js"></script>',
            settings.STATIC_URL, version)
    else:
        return format_html(
            '<script src="//ajax.googleapis.com/ajax/libs/jqueryui/{v}/jquery-ui.min.js"></script>'
            '<script>window.jQuery.ui || document.write(\'<script src="{static}djfrontend/js/jquery/jqueryui/{v}/jquery-ui.min.js"><\/script>\')</script>',
            static=_static_url, v=version)


Instruction:
Can you generate a brief explanation for the following Python 3 code
def djfrontend_jquery_datatables(version=None):
    if version is None:
        if not getattr(settings, 'DJFRONTEND_JQUERY_DATATABLES', False):
            version = getattr(settings, 'DJFRONTEND_JQUERY_DATATABLES_VERSION', DJFRONTEND_JQUERY_DATATABLES_VERSION_DEFAULT)
        else:
            version = getattr(settings, 'DJFRONTEND_JQUERY_DATATABLES', DJFRONTEND_JQUERY_DATATABLES_VERSION_DEFAULT)

    if getattr(settings, 'TEMPLATE_DEBUG', False):
        template = '<script src="{static}djfrontend/js/jquery/jquery.dataTables/{v}/jquery.dataTables.js"></script>'
    else:
        template = (
            '<script src="//cdnjs.cloudflare.com/ajax/libs/datatables/{v}/jquery.dataTables.min.js"></script>'
            '<script>window.jQuery.fn.DataTable || document.write(\'<script src="{static}djfrontend/js/jquery/jquery.dataTables/{v}/jquery.dataTables.min.js"><\/script>\')</script>')
    return format_html(template, static=_static_url, v=version)

Response: Returns the jQuery DataTables plugin file according to version number.


Instruction:
Can you generate the documentation for the following Python 3 function
def djfrontend_jquery_datatables_css(version=None):
    if version is None:
        if not getattr(settings, 'DJFRONTEND_JQUERY_DATATABLES_CSS', False):
            version = getattr(settings, 'DJFRONTEND_JQUERY_DATATABLES_VERSION', DJFRONTEND_JQUERY_DATATABLES_VERSION_DEFAULT)
        else:
            version = getattr(settings, 'DJFRONTEND_JQUERY_DATATABLES_CSS', DJFRONTEND_JQUERY_DATATABLES_VERSION_DEFAULT)

    return format_html(
        '<link rel="stylesheet" href="{static}djfrontend/css/jquery/jquery.dataTables/{v}/jquery.dataTables{min}.css">',
        static=_static_url, v=version, min=_min)

Response: Returns the jQuery DataTables CSS file according to version number.


Instruction:
Make a summary of the following Python 3 code
def djfrontend_jquery_datatables_themeroller(version=None):
    if version is None:
        if not getattr(settings, 'DJFRONTEND_JQUERY_DATATABLES_THEMEROLLER', False):
            version = getattr(settings, 'DJFRONTEND_JQUERY_DATATABLES_VERSION', DJFRONTEND_JQUERY_DATATABLES_VERSION_DEFAULT)
        else:
            version = getattr(settings, 'DJFRONTEND_JQUERY_DATATABLES_THEMEROLLER', DJFRONTEND_JQUERY_DATATABLES_VERSION_DEFAULT)

    return format_html(
        '<link rel="stylesheet" href="href="{static}djfrontend/css/jquery/jquery.dataTables/{v}/jquery.dataTables_themeroller.min.css">',
        static=_static_url, v=version)

Response: Returns the jQuery DataTables ThemeRoller CSS file according to version number.


Instruction:
Implement a Python 3 function for
returning the jQuery Dynamic Formset plugin file according to version number.

Response:
def djfrontend_jquery_formset(version=None):
    """
    Returns the jQuery Dynamic Formset plugin file according to version number.
    TEMPLATE_DEBUG returns full file, otherwise returns minified file.
    """
    if version is None:
        version = getattr(settings, 'DJFRONTEND_JQUERY_FORMSET', DJFRONTEND_JQUERY_FORMSET_DEFAULT)

    if getattr(settings, 'TEMPLATE_DEBUG', False):
        template = '<script src="{static}djfrontend/js/jquery/jquery.formset/{v}/jquery.formset.js"></script>'
    else:
        template = (
            '<script src="//cdnjs.cloudflare.com/ajax/libs/jquery.formset/{v}/jquery.formset.min.js"></script>\n'
            '<script>window.jQuery.fn.formset || document.write(\'<script src="{static}djfrontend/js/jquery/jquery.formset/{v}/jquery.formset.min.js"><\/script>\')</script>')
    return format_html(template, static=_static_url, v=version)


Instruction:
How would you explain what the following Python 3 function does
def djfrontend_jquery_scrollto(version=None):
    if version is None:
        version = getattr(settings, 'DJFRONTEND_JQUERY_SCROLLTO', DJFRONTEND_JQUERY_SCROLLTO_DEFAULT)

    if getattr(settings, 'TEMPLATE_DEBUG', False):
        template = '<script src="{static}djfrontend/js/jquery/jquery.scrollTo/{v}/jquery.scrollTo.js"></script>'
    else:
        template = (
            '<script src="//cdnjs.cloudflare.com/ajax/libs/jquery-scrollTo/{v}/jquery.scrollTo.min.js"></script>'
            '<script>window.jQuery.fn.scrollTo || document.write(\'<script src="{static}djfrontend/js/jquery/jquery.scrollTo/{v}/jquery.scrollTo.min.js"><\/script>\')</script>')
    return format_html(template, static=_static_url, v=version)

Response: Returns the jQuery ScrollTo plugin file according to version number.


Instruction:
Make a summary of the following Python 3 code
def djfrontend_jquery_smoothscroll(version=None):
    if version is None:
        version = getattr(settings, 'DJFRONTEND_JQUERY_SMOOTHSCROLL', DJFRONTEND_JQUERY_SMOOTHSCROLL_DEFAULT)

    if getattr(settings, 'TEMPLATE_DEBUG', False):
        template = '<script src="{static}djfrontend/js/jquery/jquery.smooth-scroll/{v}/jquery.smooth-scroll.js"></script>'
    else:
        template = (
            '<script src="//cdnjs.cloudflare.com/ajax/libs/jquery-smooth-scroll/{v}/jquery.smooth-scroll.min.js"></script>'
            '<script>window.jQuery.fn.smoothScroll || document.write(\'<script src="{static}djfrontend/js/jquery/jquery.smooth-scroll/{v}/jquery.smooth-scroll.min.js"><\/script>\')</script>')
    return format_html(template, static=_static_url, v=version)

Response: Returns the jQuery Smooth Scroll plugin file according to version number.


Instruction:
Make a summary of the following Python 3 code
def djfrontend_twbs_css(version=None):
    if version is None:
        if not getattr(settings, 'DJFRONTEND_TWBS_CSS', False):
            version = getattr(settings, 'DJFRONTEND_TWBS_VERSION', DJFRONTEND_TWBS_VERSION_DEFAULT)
        else:
             version = getattr(settings, 'DJFRONTEND_TWBS_CSS', DJFRONTEND_TWBS_VERSION_DEFAULT)

    return format_html(
        '<link rel="stylesheet" href="{static}djfrontend/css/twbs/{v}/bootstrap{min}.css">',
        static=_static_url, v=version, min=_min)

Response: Returns the Twitter Bootstrap CSS file.