Instruction:
Write a Python 3 script for
converting a value to a datetime object.

Response:
def convert_datetime(value, parameter):
    '''
    Converts to datetime.datetime:
        '', '-', None convert to parameter default
        The first matching format in settings.DATETIME_INPUT_FORMATS converts to datetime
    '''
    value = _check_default(value, parameter, ( '', '-', None ))
    if value is None or isinstance(value, datetime.datetime):
        return value
    for fmt in settings.DATETIME_INPUT_FORMATS:
        try:
            return datetime.datetime.strptime(value, fmt)
        except (ValueError, TypeError):
            continue
    raise ValueError("`{}` does not match a format in settings.DATETIME_INPUT_FORMATS".format(value))


Instruction:
Can you tell what is the following Python 3 function doing
def convert_date(value, parameter):
    '''
    Converts to datetime.date:
        '', '-', None convert to parameter default
        The first matching format in settings.DATE_INPUT_FORMATS converts to datetime
    '''
    value = _check_default(value, parameter, ( '', '-', None ))
    if value is None or isinstance(value, datetime.date):
        return value
    for fmt in settings.DATE_INPUT_FORMATS:
        try:
            return datetime.datetime.strptime(value, fmt).date()
        except (ValueError, TypeError):
            continue
    raise ValueError("`{}` does not match a format in settings.DATE_INPUT_FORMATS".format(value))

Response: Converts a value to a datetime. date object.


Instruction:
Can you generate the documentation for the following Python 3 function
def convert_id_to_model(value, parameter):
    '''
    Converts to a Model object.
        '', '-', '0', None convert to parameter default
        Anything else is assumed an object id and sent to `.get(id=value)`.
    '''
    value = _check_default(value, parameter, ( '', '-', '0', None ))
    if isinstance(value, (int, str)):  # only convert if we have the id
        try:
            return parameter.type.objects.get(id=value)
        except (MultipleObjectsReturned, ObjectDoesNotExist) as e:
            raise ValueError(str(e))
    return value

Response: Converts an id to a Model object.


Instruction:
Explain what the following Python 3 code does
def _check_default(value, parameter, default_chars):
    '''Returns the default if the value is "empty"'''
    # not using a set here because it fails when value is unhashable
    if value in default_chars:
        if parameter.default is inspect.Parameter.empty:
            raise ValueError('Value was empty, but no default value is given in view function for parameter: {} ({})'.format(parameter.position, parameter.name))
        return parameter.default
    return value

Response: Checks if the value is empty and returns the default if it is empty


Instruction:
Can you tell what is the following Python 3 function doing
def protocol(handler, cfg):
    # Stages
    if 'stages' not in cfg:
        raise ValueError('Protocol must include stages of simulation')

    pos, vel, box = handler.positions, handler.velocities, handler.box
    stages = cfg.pop('stages')
    for stage_options in stages:
        options = DEFAULT_OPTIONS.copy()
        options.update(cfg)
        stage_system_options = prepare_system_options(stage_options)
        options.update(stage_options)
        options['system_options'].update(stage_system_options)
        stage = Stage(handler, positions=pos, velocities=vel, box=box,
                      total_stages=len(stages), **options)
        pos, vel, box = stage.run()
        del stage

Response: Run all the stages in protocol


Instruction:
How would you explain what the following Python 3 function does
def run(self):
        if self.verbose:
            status = '#{}'.format(self.stage_index)
            if self.total_stages is not None:
                status += '/{}'.format(self.total_stages)
            status += ': {}'.format(self.name)
            pieces = []
            if self.restrained_atoms is not None:
                pieces.append('restrained {}'.format(self.restrained_atoms))
            if self.constrained_atoms is not None:
                pieces.append('constrained {}'.format(self.constrained_atoms))
            if self.distance_restrained_atoms is not None:
                pieces.append('distance restrained for {} atom pairs'.format(len(self.distance_restrained_atoms)))
            if pieces:
                status += ' [{}]'.format(', '.join(pieces))
            logger.info(status)

        # Add forces
        self.apply_restraints()
        self.apply_constraints()

        if self.barostat:
            self.apply_barostat()

        if self.minimization:
            if self.verbose:
                logger.info('  Minimizing...')
            self.minimize()

        uses_pbc = self.system.usesPeriodicBoundaryConditions()
        if self.steps:
            # Stdout progress
            if self.report and self.progress_reporter not in self.simulation.reporters:
                self.simulation.reporters.append(self.progress_reporter)

            # Log report
            if self.report and self.log_reporter not in self.simulation.reporters:
                self.simulation.reporters.append(self.log_reporter)

            # Trajectory / movie files
            if self.trajectory and self.trajectory_reporter not in self.simulation.reporters:
                self.simulation.reporters.append(self.trajectory_reporter)

            # Checkpoint or restart files
            if self.restart and self.restart_reporter not in self.simulation.reporters:
                self.simulation.reporters.append(self.restart_reporter)

            # MD simulation
            if self.verbose:
                pbc = 'PBC ' if uses_pbc else ''
                conditions = 'NPT' if self.barostat else 'NVT'
                logger.info('  Running {}MD for {} steps @ {}K, {}'.format(pbc, self.steps,
                                                                     self.temperature,
                                                                     conditions))

            with self.handle_exceptions():
                self.simulate()

        if self.save_state_at_end:
            path = self.new_filename(suffix='.state')
            self.simulation.saveState(path)

        # Save and return state
        state = self.simulation.context.getState(getPositions=True, getVelocities=True,
                                                 enforcePeriodicBox=uses_pbc)

        return state.getPositions(), state.getVelocities(), state.getPeriodicBoxVectors()

Response: Runs the MD simulation.


Instruction:
Write a Python 3 script to
minimize energy of the system until meeting tolerance or max_iterations.

Response:
def minimize(self, tolerance=None, max_iterations=None):
        """
        Minimize energy of the system until meeting `tolerance` or
        performing `max_iterations`.
        """
        if tolerance is None:
            tolerance = self.minimization_tolerance
        if max_iterations is None:
            max_iterations = self.minimization_max_iterations
        self.simulation.minimizeEnergy(tolerance * u.kilojoules_per_mole, max_iterations)


Instruction:
Write a Python 3 function that can
advance simulation n steps

Response:
def simulate(self, steps=None):
        """
        Advance simulation n steps
        """
        if steps is None:
            steps = self.steps
        self.simulation.step(steps)


Instruction:
Write a Python 3 function for
returning a custom force that restrains atoms to fix their positions while allowing severe clashes and so on.

Response:
def restraint_force(self, indices=None, strength=5.0):
        """
        Force that restrains atoms to fix their positions, while allowing
        tiny movement to resolve severe clashes and so on.

        Returns
        -------
        force : simtk.openmm.CustomExternalForce
            A custom force to restrain the selected atoms
        """
        if self.system.usesPeriodicBoundaryConditions():
            expression = 'k*periodicdistance(x, y, z, x0, y0, z0)^2'
        else:
            expression = 'k*((x-x0)^2 + (y-y0)^2 + (z-z0)^2)'
        force = mm.CustomExternalForce(expression)
        force.addGlobalParameter('k', strength*u.kilocalories_per_mole/u.angstroms**2)
        force.addPerParticleParameter('x0')
        force.addPerParticleParameter('y0')
        force.addPerParticleParameter('z0')
        positions = self.positions if self.positions is not None else self.handler.positions
        if indices is None:
            indices = range(self.handler.topology.getNumAtoms())
        for i, index in enumerate(indices):
            force.addParticle(i, positions[index].value_in_unit(u.nanometers))
        return force


Instruction:
Implement a function in Python 3 to
return a force for a set of atoms and distances.

Response:
def distance_restraint_force(self, atoms, distances, strengths):
        """
        Parameters
        ----------
        atoms : tuple of tuple of int or str
            Pair of atom indices to be restrained, with shape (n, 2),
            like ((a1, a2), (a3, a4)). Items can be str compatible with MDTraj DSL.
        distances : tuple of float
            Equilibrium distances for each pair
        strengths : tuple of float
            Force constant for each pair
        """
        system = self.system
        force = mm.HarmonicBondForce()
        force.setUsesPeriodicBoundaryConditions(self.system.usesPeriodicBoundaryConditions())
        for pair, distance, strength in zip(atoms, distances, strengths):
            indices = []
            for atom in pair:
                if isinstance(atom, str):
                    index = self.subset(atom)
                    if len(index) != 1:
                        raise ValueError('Distance restraint for selection `{}` returns != 1 atom!: {}'
                                         .format(atom, index))
                    indices.append(int(index[0]))
                elif isinstance(atom, (int, float)):
                    indices.append(int(atom))
                else:
                    raise ValueError('Distance restraint atoms must be int or str DSL selections')
            if distance == 'current':
                pos = self.positions or system.positions
                distance = np.linalg.norm(pos[indices[0]] - pos[indices[1]])

            force.addBond(indices[0], indices[1], distance*u.nanometers,
                          strength*u.kilocalories_per_mole/u.angstroms**2)
        return force


Instruction:
How would you explain what the following Python 3 function does
def subset(self, selector):
        if isinstance(selector, (list, tuple)):
            return map(int, selector)
        selector = SELECTORS.get(selector, selector)
        mdtop = MDTrajTopology.from_openmm(self.handler.topology)
        return mdtop.select(selector)

Response:
Returns a list of atom indices corresponding to a MDTraj DSL
        query.


Instruction:
Given the following Python 3 function, write the documentation
def handle_exceptions(self, verbose=True):
        try:
            yield
        except (KeyboardInterrupt, Exception) as ex:
            if not self.attempt_rescue:
                raise ex
            if isinstance(ex, KeyboardInterrupt):
                reraise = False
                answer = timed_input('\n\nDo you want to save current state? (y/N): ')
                if answer and answer.lower() not in ('y', 'yes'):
                    if verbose:
                        sys.exit('Ok, bye!')
            else:
                reraise = True
                logger.error('\n\nAn error occurred: %s', ex)
            if verbose:
                logger.info('Saving state...')
            try:
                self.backup_simulation()
            except Exception:
                if verbose:
                    logger.error('FAILED :(')
            else:
                if verbose:
                    logger.info('SUCCESS!')
            finally:
                if reraise:
                    raise ex
                sys.exit()

Response: Handle exceptions and attempt to save the current state of the simulation.


Instruction:
Can you tell what is the following Python 3 function doing
def backup_simulation(self):
        path = self.new_filename(suffix='_emergency.state')
        self.simulation.saveState(path)
        uses_pbc = self.system.usesPeriodicBoundaryConditions()
        state_kw = dict(getPositions=True, getVelocities=True,
                        getForces=True, enforcePeriodicBox=uses_pbc,
                        getParameters=True, getEnergy=True)
        state = self.simulation.context.getState(**state_kw)
        for reporter in self.simulation.reporters:
            if not isinstance(reporter, app.StateDataReporter):
                reporter.report(self.simulation, state)

Response: Creates an emergency report run and saves the state of the simulation context to disk.


Instruction:
Write a Python 3 script for
getting parse and prepare input file.

Response:
def prepare_input(argv=None):
    """
    Get, parse and prepare input file.
    """
    p = ArgumentParser(description='InsiliChem Ommprotocol: '
                       'easy to deploy MD protocols for OpenMM')
    p.add_argument('input', metavar='INPUT FILE', type=extant_file,
                   help='YAML input file')
    p.add_argument('--version', action='version', version='%(prog)s v{}'.format(__version__))
    p.add_argument('-c', '--check', action='store_true',
                   help='Validate input file only')
    args = p.parse_args(argv if argv else sys.argv[1:])

    jinja_env = jinja2.Environment(trim_blocks=True, lstrip_blocks=True)
    # Load config file
    with open(args.input) as f:
        rendered = jinja_env.from_string(f.read()).render()
        cfg = yaml.load(rendered, Loader=YamlLoader)
    # Paths and dirs
    from .md import SYSTEM_OPTIONS
    cfg['_path'] = os.path.abspath(args.input)
    cfg['system_options'] = prepare_system_options(cfg, defaults=SYSTEM_OPTIONS)
    cfg['outputpath'] = sanitize_path_for_file(cfg.get('outputpath', '.'), args.input)

    if not args.check:
        with ignored_exceptions(OSError):
            os.makedirs(cfg['outputpath'])

    handler = prepare_handler(cfg)

    return handler, cfg, args


Instruction:
Implement a Python 3 function for
loading all files into single object.

Response:
def prepare_handler(cfg):
    """
    Load all files into single object.
    """
    positions, velocities, box = None, None, None
    _path = cfg.get('_path', './')
    forcefield = cfg.pop('forcefield', None)
    topology_args = sanitize_args_for_file(cfg.pop('topology'), _path)

    if 'checkpoint' in cfg:
        restart_args = sanitize_args_for_file(cfg.pop('checkpoint'), _path)
        restart = Restart.load(*restart_args)
        positions = restart.positions
        velocities = restart.velocities
        box = restart.box

    if 'positions' in cfg:
        positions_args = sanitize_args_for_file(cfg.pop('positions'), _path)
        positions = Positions.load(*positions_args)
        box = BoxVectors.load(*positions_args)

    if 'velocities' in cfg:
        velocities_args = sanitize_args_for_file(cfg.pop('velocities'), _path)
        velocities = Velocities.load(*velocities_args)

    if 'box' in cfg:
        box_args = sanitize_args_for_file(cfg.pop('box'), _path)
        box = BoxVectors.load(*box_args)

    options = {}
    for key in 'positions velocities box forcefield'.split():
        value = locals()[key]
        if value is not None:
            options[key] = value

    return SystemHandler.load(*topology_args, **options)


Instruction:
Can you tell what is the following Python 3 function doing
def prepare_system_options(cfg, defaults=None):
    d = {} if defaults is None else defaults.copy()
    if 'nonbondedMethod' in cfg:
        d['nonbondedMethod'] = warned_getattr(openmm_app, cfg.pop('nonbondedMethod'), None)
    if 'nonbondedCutoff' in cfg:
        d['nonbondedCutoff'] = cfg.pop('nonbondedCutoff') * u.nanometers
    if 'constraints' in cfg:
        d['constraints'] = warned_getattr(openmm_app, cfg.pop('constraints'), None)
    for key in ['rigidWater', 'ewaldErrorTolerance']:
        if key in cfg:
            d[key] = cfg.pop(key)
    if 'extra_system_options' in cfg:
        if 'implicitSolvent' in cfg['extra_system_options']:
            implicit_solvent = warned_getattr(
                openmm_app, cfg['extra_system_options']['implicitSolvent'], None)
            cfg['extra_system_options']['implicitSolvent'] = implicit_solvent
        d.update(cfg.pop('extra_system_options'))
    return d

Response: Retrieve and delete system options from input configuration.


Instruction:
Make a summary of the following Python 3 code
def process_forcefield(*forcefields):
    for forcefield in forcefields:
        if forcefield.endswith('.frcmod'):
            gaffmol2 = os.path.splitext(forcefield)[0] + '.gaff.mol2'
            yield create_ffxml_file([gaffmol2], [forcefield])
        else:
            yield forcefield

Response: Yields a list of filenames if they are frcmods.


Instruction:
Given the following Python 3 function, write the documentation
def statexml2pdb(topology, state, output=None):
    state = Restart.from_xml(state)
    system = SystemHandler.load(topology, positions=state.positions)
    if output is None:
        output = topology + '.pdb'
    system.write_pdb(output)

Response: Given an OpenMM xml file containing the state of the simulation generate a PDB snapshot for easy visualization.


Instruction:
Create a Python 3 function to
extract a single frame structure from a trajectory.

Response:
def export_frame_coordinates(topology, trajectory, nframe, output=None):
    """
    Extract a single frame structure from a trajectory.
    """
    if output is None:
        basename, ext = os.path.splitext(trajectory)
        output = '{}.frame{}.inpcrd'.format(basename, nframe)

    # ParmEd sometimes struggles with certain PRMTOP files
    if os.path.splitext(topology)[1] in ('.top', '.prmtop'):
        top = AmberPrmtopFile(topology)
        mdtop = mdtraj.Topology.from_openmm(top.topology)
        traj = mdtraj.load_frame(trajectory, int(nframe), top=mdtop)
        structure = parmed.openmm.load_topology(top.topology, system=top.createSystem())
        structure.box_vectors = top.topology.getPeriodicBoxVectors()

    else:  # standard protocol (the topology is loaded twice, though)
        traj = mdtraj.load_frame(trajectory, int(nframe), top=topology)
        structure = parmed.load_file(topology)

    structure.positions = traj.openmm_positions(0)

    if traj.unitcell_vectors is not None:  # if frame provides box vectors, use those
        structure.box_vectors = traj.openmm_boxes(0)

    structure.save(output, overwrite=True)


Instruction:
Make a summary of the following Python 3 code
def construct_include(self, node):

        filename = os.path.join(self._root, self.construct_scalar(node))
        filename = os.path.abspath(filename)
        extension = os.path.splitext(filename)[1].lstrip('.')

        with open(filename, 'r') as f:
            if extension in ('yaml', 'yml'):
                return yaml.load(f, Loader=self)
            else:
                return ''.join(f.readlines())

Response: Construct include file referenced at node.


Instruction:
Can you generate the documentation for the following Python 3 function
def from_pdb(cls, path, forcefield=None, loader=PDBFile, strict=True, **kwargs):
        pdb = loader(path)
        box = kwargs.pop('box', pdb.topology.getPeriodicBoxVectors())
        positions = kwargs.pop('positions', pdb.positions)
        velocities = kwargs.pop('velocities', getattr(pdb, 'velocities', None))

        if strict and not forcefield:
            from .md import FORCEFIELDS as forcefield
            logger.info('! Forcefields for PDB not specified. Using default: %s',
                        ', '.join(forcefield))
        pdb.forcefield = ForceField(*list(process_forcefield(*forcefield)))

        return cls(master=pdb.forcefield, topology=pdb.topology, positions=positions,
                   velocities=velocities, box=box, path=path, **kwargs)

Response: Loads a SystemHandler from a PDB file.


Instruction:
How would you code a function in Python 3 to
load a SystemHandler from an Amber. prmtop file.

Response:
def from_amber(cls, path, positions=None, strict=True, **kwargs):
        """
        Loads Amber Parm7 parameters and topology file

        Parameters
        ----------
        path : str
            Path to *.prmtop or *.top file
        positions : simtk.unit.Quantity
            Atomic positions

        Returns
        -------
        prmtop : SystemHandler
            SystemHandler with topology
        """
        if strict and positions is None:
            raise ValueError('Amber TOP/PRMTOP files require initial positions.')
        prmtop = AmberPrmtopFile(path)
        box = kwargs.pop('box', prmtop.topology.getPeriodicBoxVectors())
        return cls(master=prmtop, topology=prmtop.topology, positions=positions, box=box,
                   path=path, **kwargs)


Instruction:
Can you generate a brief explanation for the following Python 3 code
def from_charmm(cls, path, positions=None, forcefield=None, strict=True, **kwargs):
        psf = CharmmPsfFile(path)
        if strict and forcefield is None:
            raise ValueError('PSF files require key `forcefield`.')
        if strict and positions is None:
            raise ValueError('PSF files require key `positions`.')
        psf.parmset = CharmmParameterSet(*forcefield)
        psf.loadParameters(psf.parmset)
        return cls(master=psf, topology=psf.topology, positions=positions, path=path,
                   **kwargs)

Response: Loads a SystemHandler from a Charmm structure file.


Instruction:
Can you implement a function in Python 3 that
loads a topology from a Desmond DMS file located at path.

Response:
def from_desmond(cls, path, **kwargs):
        """
        Loads a topology from a Desmond DMS file located at `path`.

        Arguments
        ---------
        path : str
            Path to a Desmond DMS file
        """
        dms = DesmondDMSFile(path)
        pos = kwargs.pop('positions', dms.getPositions())
        return cls(master=dms, topology=dms.getTopology(), positions=pos, path=path,
                   **kwargs)


Instruction:
How would you explain what the following Python 3 function does
def from_gromacs(cls, path, positions=None, forcefield=None, strict=True, **kwargs):
        if strict and positions is None:
            raise ValueError('Gromacs TOP files require initial positions.')
        box = kwargs.pop('box', None)
        top = GromacsTopFile(path, includeDir=forcefield, periodicBoxVectors=box)
        return cls(master=top, topology=top.topology, positions=positions, box=box,
                   path=path, **kwargs)

Response: Loads a topology from a Gromacs TOP file located at path.


Instruction:
Can you tell what is the following Python 3 function doing
def from_parmed(cls, path, *args, **kwargs):
        st = parmed.load_file(path, structure=True, *args, **kwargs)
        box = kwargs.pop('box', getattr(st, 'box', None))
        velocities = kwargs.pop('velocities', getattr(st, 'velocities', None))
        positions = kwargs.pop('positions', getattr(st, 'positions', None))
        return cls(master=st, topology=st.topology, positions=positions, box=box,
                   velocities=velocities, path=path, **kwargs)

Response: Load a new object from a ParmEd file.


Instruction:
Write a Python 3 script for
loading pickled topology. Careful with Python versions though!

Response:
def _pickle_load(path):
        """
        Loads pickled topology. Careful with Python versions though!
        """
        _, ext = os.path.splitext(path)
        topology = None
        if sys.version_info.major == 2:
            if ext == '.pickle2':
                with open(path, 'rb') as f:
                    topology = pickle.load(f)
            elif ext in ('.pickle3', '.pickle'):
                with open(path, 'rb') as f:
                    topology = pickle.load(f, protocol=3)
        elif sys.version_info.major == 3:
            if ext == '.pickle2':
                with open(path, 'rb') as f:
                    topology = pickle.load(f)
            elif ext in ('.pickle3', '.pickle'):
                with open(path, 'rb') as f:
                    topology = pickle.load(f)
        if topology is None:
            raise ValueError('File {} is not compatible with this version'.format(path))
        return topology


Instruction:
Write a Python 3 script to
create an OpenMM system for every supported topology file with given system options.

Response:
def create_system(self, **system_options):
        """
        Create an OpenMM system for every supported topology file with given system options
        """
        if self.master is None:
            raise ValueError('Handler {} is not able to create systems.'.format(self))

        if isinstance(self.master, ForceField):
            system = self.master.createSystem(self.topology, **system_options)
        elif isinstance(self.master, (AmberPrmtopFile, GromacsTopFile, DesmondDMSFile)):
            system = self.master.createSystem(**system_options)
        elif isinstance(self.master, CharmmPsfFile):
            if not hasattr(self.master, 'parmset'):
                raise ValueError('PSF topology files require Charmm parameters.')
            system = self.master.createSystem(self.master.parmset, **system_options)
        else:
            raise NotImplementedError('Handler {} is not able to create systems.'.format(self))

        if self.has_box:
            system.setDefaultPeriodicBoxVectors(*self.box)
        return system


Instruction:
Write a Python 3 script for
outputting a PDB file with the current contents of the system.

Response:
def write_pdb(self, path):
        """
        Outputs a PDB file with the current contents of the system
        """
        if self.master is None and self.positions is None:
            raise ValueError('Topology and positions are needed to write output files.')
        with open(path, 'w') as f:
            PDBFile.writeFile(self.topology, self.positions, f)


Instruction:
Can you generate the documentation for the following Python 3 function
def from_xsc(cls, path):

        def parse(path):
            """
            Open and parses an XSC file into its fields

            Parameters
            ----------
            path : str
                Path to XSC file

            Returns
            -------
            namedxsc : namedtuple
                A namedtuple with XSC fields as names
            """
            with open(path) as f:
                lines = f.readlines()
            NamedXsc = namedtuple('NamedXsc', lines[1].split()[1:])
            return NamedXsc(*map(float, lines[2].split()))

        xsc = parse(path)
        return u.Quantity([[xsc.a_x, xsc.a_y, xsc.a_z],
                           [xsc.b_x, xsc.b_y, xsc.b_z],
                           [xsc.c_x, xsc.c_y, xsc.c_z]], unit=u.angstroms)

Response: Returns u. Quantity with box vectors from XSC file


Instruction:
Can you generate the documentation for the following Python 3 function
def from_csv(cls, path):
        with open(path) as f:
            fields = map(float, next(f).split(','))
        if len(fields) == 3:
            return u.Quantity([[fields[0], 0, 0],
                               [0, fields[1], 0],
                               [0, 0, fields[2]]], unit=u.nanometers)
        elif len(fields) == 9:
            return u.Quantity([fields[0:3],
                               fields[3:6],
                               fields[6:9]], unit=u.nanometers)
        else:
            raise ValueError('This type of CSV is not supported. Please '
                             'provide a comma-separated list of three or nine '
                             'floats in a single-line file.')

Response: Returns a new instance of the class u. Quantity object from a CSV file.


Instruction:
Can you generate the documentation for the following Python 3 function
def describeNextReport(self, simulation):
        steps = self.interval - simulation.currentStep % self.interval
        return steps, False, False, False, False

Response: Get information about the next report for this object.


Instruction:
Make a summary of the following Python 3 code
def report(self, simulation, state):
        if not self._initialized:
            self._initial_clock_time = datetime.now()
            self._initial_simulation_time = state.getTime()
            self._initial_steps = simulation.currentStep
            self._initialized = True

        steps = simulation.currentStep
        time = datetime.now() - self._initial_clock_time
        days = time.total_seconds()/86400.0
        ns = (state.getTime()-self._initial_simulation_time).value_in_unit(u.nanosecond)

        margin = ' ' * self.margin
        ns_day = ns/days
        delta = ((self.total_steps-steps)*time.total_seconds())/steps
        # remove microseconds to have cleaner output
        remaining = timedelta(seconds=int(delta))
        percentage = 100.0*steps/self.total_steps
        if ns_day:
            template = '{}{}/{} steps ({:.1f}%) - {} left @ {:.1f} ns/day                    \r'
        else:
            template = '{}{}/{} steps ({:.1f}%)                                              \r'
        report = template.format(margin, steps, self.total_steps, percentage, remaining, ns_day)
        self._out.write(report)
        if hasattr(self._out, 'flush'):
            self._out.flush()

Response:
Generate a report.

        Parameters
        ----------
        simulation : Simulation
            The Simulation to generate a report for
        state : State
            The current state of the simulation


Instruction:
Can you generate the documentation for the following Python 3 function
def report(self, simulation, state):
        if not self._initialized:
            self._initialized = True

        self._steps[0] += self.interval
        positions = state.getPositions()

        # Serialize
        self._out.write(b''.join([b'\nSTARTOFCHUNK\n',
                                  pickle.dumps([self._steps[0], positions._value]),
                                  b'\nENDOFCHUNK\n']))
        if hasattr(self._out, 'flush'):
            self._out.flush()

Response:
Generate a report.

        Parameters
        ----------
        simulation : Simulation
            The Simulation to generate a report for
        state : State
            The current state of the simulation


Instruction:
Explain what the following Python 3 code does
def assert_not_exists(path, sep='.'):
    name, ext = os.path.splitext(path)
    i = 1
    while os.path.exists(path):
        path = '{}{}{}{}'.format(name, sep, i, ext)
        i += 1
    return path

Response: Checks if a file does not exist.


Instruction:
Write a Python 3 function that can
make sure object obj is of type types. Else raise TypeError.

Response:
def assertinstance(obj, types):
    """
    Make sure object `obj` is of type `types`. Else, raise TypeError.
    """
    if isinstance(obj, types):
        return obj
    raise TypeError('{} must be instance of {}'.format(obj, types))


Instruction:
Can you generate the documentation for the following Python 3 function
def extant_file(path):
    if not os.path.exists(path):
        raise argparse.ArgumentTypeError("{} does not exist".format(path))
    return path

Response: Check if file exists with argparse. ArgumentParser


Instruction:
Create a Python 3 function to
sort files taking into account potentially absent suffixes like 2000. 1000. 2000.

Response:
def sort_key_for_numeric_suffixes(path, sep='.', suffix_index=-2):
    """
    Sort files taking into account potentially absent suffixes like
        somefile.dcd
        somefile.1000.dcd
        somefile.2000.dcd

    To be used with sorted(..., key=callable).
    """
    chunks = path.split(sep)
    # Remove suffix from path and convert to int
    if chunks[suffix_index].isdigit():
        return sep.join(chunks[:suffix_index] + chunks[suffix_index+1:]), int(chunks[suffix_index])
    return path, 0


Instruction:
Can you generate the documentation for the following Python 3 function
def json_response(f, *args, **kwargs):
    try:
        result = f(*args, **kwargs)
        if isinstance(result, AJAXError):
            raise result
    except AJAXError as e:
        result = e.get_response()

        request = args[0]
        logger.warn('AJAXError: %d %s - %s', e.code, request.path, e.msg,
            exc_info=True,
            extra={
                'status_code': e.code,
                'request': request
            }
        )
    except Http404 as e:
        result = AJAXError(404, e.__str__()).get_response()
    except Exception as e:
        import sys
        exc_info = sys.exc_info()
        type, message, trace = exc_info
        if settings.DEBUG:
            import traceback
            tb = [{'file': l[0], 'line': l[1], 'in': l[2], 'code': l[3]} for
                l in traceback.extract_tb(trace)]
            result = AJAXError(500, message, traceback=tb).get_response()
        else:
            result = AJAXError(500, "Internal server error.").get_response()

        request = args[0]
        logger.error('Internal Server Error: %s' % request.path,
            exc_info=exc_info,
            extra={
                'status_code': 500,
                'request': request
            }
        )

    result['Content-Type'] = 'application/json'
    return result

Response: A decorator that wraps a view in JSON.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def import_by_path(dotted_path, error_prefix=''):
    try:
        module_path, class_name = dotted_path.rsplit('.', 1)
    except ValueError:
        raise ImproperlyConfigured("%s%s doesn't look like a module path" % (
            error_prefix, dotted_path))
    try:
        module = import_module(module_path)
    except ImportError as e:
        raise ImproperlyConfigured('%sError importing module %s: "%s"' % (
            error_prefix, module_path, e))
    try:
        attr = getattr(module, class_name)
    except AttributeError:
        raise ImproperlyConfigured(
            '%sModule "%s" does not define a "%s" attribute/class' % (
                error_prefix, module_path, class_name
            )
        )
    return attr

Response: Imports a dotted module path and returns the attribute or class designated by the last name in the path. Raise ImproperlyConfigured if something goes wrong.


Instruction:
Create a Python 3 function for
loading an AJAX endpoint. This will load either an ad-hoc endpoint or it will load up a model endpoint depending on what it finds. It first attempts to load ``model`` as if it were an ad-hoc endpoint. Alternatively, it will attempt to see if there is a ``ModelEndpoint`` for the given ``model``.

Response:
def endpoint_loader(request, application, model, **kwargs):
    """Load an AJAX endpoint.

    This will load either an ad-hoc endpoint or it will load up a model
    endpoint depending on what it finds. It first attempts to load ``model``
    as if it were an ad-hoc endpoint. Alternatively, it will attempt to see if
    there is a ``ModelEndpoint`` for the given ``model``.
    """
    if request.method != "POST":
        raise AJAXError(400, _('Invalid HTTP method used.'))

    try:
        module = import_module('%s.endpoints' % application)
    except ImportError as e:
        if settings.DEBUG:
            raise e
        else:
            raise AJAXError(404, _('AJAX endpoint does not exist.'))

    if hasattr(module, model):
        # This is an ad-hoc endpoint
        endpoint = getattr(module, model)
    else:
        # This is a model endpoint
        method = kwargs.get('method', 'create').lower()
        try:
            del kwargs['method']
        except:
            pass

        try:
            model_endpoint = ajax.endpoint.load(model, application, method,
                **kwargs)
            if not model_endpoint.authenticate(request, application, method):
                raise AJAXError(403, _('User is not authorized.'))

            endpoint = getattr(model_endpoint, method, False)

            if not endpoint:
                raise AJAXError(404, _('Invalid method.'))
        except NotRegistered:
            raise AJAXError(500, _('Invalid model.'))

    data = endpoint(request)
    if isinstance(data, HttpResponse):
        return data

    if isinstance(data, EnvelopedResponse):
        envelope = data.metadata
        payload = data.data
    else:
        envelope = {}
        payload = data

    envelope.update({
        'success': True,
        'data': payload,
    })

    return HttpResponse(json.dumps(envelope, cls=DjangoJSONEncoder,
        separators=(',', ':')))


Instruction:
How would you explain what the following Python 3 function does
def list(self, request):

        max_items_per_page = getattr(self, 'max_per_page',
                                      getattr(settings, 'AJAX_MAX_PER_PAGE', 100))
        requested_items_per_page = request.POST.get("items_per_page", 20)
        items_per_page = min(max_items_per_page, requested_items_per_page)
        current_page = request.POST.get("current_page", 1)

        if not self.can_list(request.user):
            raise AJAXError(403, _("Access to this endpoint is forbidden"))

        objects = self.get_queryset(request)

        paginator = Paginator(objects, items_per_page)

        try:
            page = paginator.page(current_page)
        except PageNotAnInteger:
            # If page is not an integer, deliver first page.
            page = paginator.page(1)
        except EmptyPage:
            # If page is out of range (e.g. 9999), return empty list.
            page = EmptyPageResult()

        data = [encoder.encode(record) for record in page.object_list]
        return EnvelopedResponse(data=data, metadata={'total': paginator.count})

Response: List objects of a model.


Instruction:
Create a Python 3 function to
extract the data from the POST request.

Response:
def _extract_data(self, request):
        """Extract data from POST.

        Handles extracting a vanilla Python dict of values that are present
        in the given model. This also handles instances of ``ForeignKey`` and
        will convert those to the appropriate object instances from the
        database. In other words, it will see that user is a ``ForeignKey`` to
        Django's ``User`` class, assume the value is an appropriate pk, and
        load up that record.
        """
        data = {}
        for field, val in six.iteritems(request.POST):
            if field in self.immutable_fields:
                continue  # Ignore immutable fields silently.

            if field in self.fields:
                field_obj = self.model._meta.get_field(field)
                val = self._extract_value(val)
                if isinstance(field_obj, models.ForeignKey):
                    if field_obj.null and not val:
                        clean_value = None
                    else:
                        clean_value = field_obj.rel.to.objects.get(pk=val)
                else:
                    clean_value = field_obj.to_python(val)
                data[smart_str(field)] = clean_value

        return data


Instruction:
Here you have a function in Python 3, explain what it does
def _get_record(self):
        if not self.pk:
            raise AJAXError(400, _('Invalid request for record.'))

        try:
            return self.model.objects.get(pk=self.pk)
        except self.model.DoesNotExist:
            raise AJAXError(404, _('%s with id of "%s" not found.') % (
                self.model.__name__, self.pk))

Response: Fetch a given record from the database along with throwing an anonymization of AJAXError.


Instruction:
Here you have a function in Python 3, explain what it does
def authenticate(self, request, application, method):
        return self.authentication.is_authenticated(request, application, method)

Response: Authenticate the AJAX request.


Instruction:
Create a Python 3 function to
get all entries of a space.

Response:
def all(self, query=None):
        """
        Gets all entries of a space.
        """

        if query is None:
            query = {}

        if self.content_type_id is not None:
            query['content_type'] = self.content_type_id

        normalize_select(query)

        return super(EntriesProxy, self).all(query=query)


Instruction:
How would you code a function in Python 3 to
get a single entry by ID.

Response:
def find(self, entry_id, query=None):
        """
        Gets a single entry by ID.
        """

        if query is None:
            query = {}

        if self.content_type_id is not None:
            query['content_type'] = self.content_type_id

        normalize_select(query)

        return super(EntriesProxy, self).find(entry_id, query=query)


Instruction:
How would you explain what the following Python 3 function does
def create(self, resource_id=None, attributes=None, **kwargs):

        if self.content_type_id is not None:
            if attributes is None:
                attributes = {}
            attributes['content_type_id'] = self.content_type_id

        return super(EntriesProxy, self).create(resource_id=resource_id, attributes=attributes)

Response: Creates an entry with a given ID and attributes.


Instruction:
How would you implement a function in Python 3 that
creates a webhook with given attributes.

Response:
def create(self, attributes=None, **kwargs):
        """
        Creates a webhook with given attributes.
        """

        return super(WebhooksProxy, self).create(resource_id=None, attributes=attributes)


Instruction:
Can you tell what is the following Python 3 function doing
def camel_case(snake_str):

    components = snake_str.split('_')
    # We capitalize the first letter of each component except the first one
    # with the 'title' method and join them together.
    return components[0] + "".join(x.title() for x in components[1:])

Response: Return a camel - cased version of a string.


Instruction:
Here you have a function in Python 3, explain what it does
def normalize_select(query):

    if 'select' not in query:
        return

    if isinstance(
            query['select'],
            str_type()):
        query['select'] = [s.strip() for s in query['select'].split(',')]

    query['select'] = [s for s
                       in query['select']
                       if not s.startswith('sys.')]

    if 'sys' not in query['select']:
        query['select'].append('sys')

Response: Normalizes the select operator in the query.


Instruction:
How would you implement a function in Python 3 that
returns the JSON representation of the environment.

Response:
def to_json(self):
        """
        Returns the JSON representation of the environment.
        """

        result = super(Environment, self).to_json()
        result.update({
            'name': self.name
        })

        return result


Instruction:
Can you tell what is the following Python 3 function doing
def content_types(self):

        return EnvironmentContentTypesProxy(self._client, self.space.id, self.id)

Response: Provides access to content types of an environment.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def entries(self):

        return EnvironmentEntriesProxy(self._client, self.space.id, self.id)

Response: Provides access to entry management methods.


Instruction:
Implement a Python 3 function for
providing access to asset management methods.

Response:
def assets(self):
        """
        Provides access to asset management methods.

        API reference: https://www.contentful.com/developers/docs/references/content-management-api/#/reference/assets

        :return: :class:`EnvironmentAssetsProxy <contentful_management.environment_assets_proxy.EnvironmentAssetsProxy>` object.
        :rtype: contentful.environment_assets_proxy.EnvironmentAssetsProxy

        Usage:

            >>> environment_assets_proxy = environment.assets()
            <EnvironmentAssetsProxy space_id="cfexampleapi" environment_id="master">
        """

        return EnvironmentAssetsProxy(self._client, self.space.id, self.id)


Instruction:
Can you implement a function in Python 3 that
provides access to locale management methods.

Response:
def locales(self):
        """
        Provides access to locale management methods.

        API reference: https://www.contentful.com/developers/docs/references/content-management-api/#/reference/locales

        :return: :class:`EnvironmentLocalesProxy <contentful_management.environment_locales_proxy.EnvironmentLocalesProxy>` object.
        :rtype: contentful.environment_locales_proxy.EnvironmentLocalesProxy

        Usage:

            >>> environment_locales_proxy = environment.locales()
            <EnvironmentLocalesProxy space_id="cfexampleapi" environment_id="master">
        """

        return EnvironmentLocalesProxy(self._client, self.space.id, self.id)


Instruction:
Given the following Python 3 function, write the documentation
def ui_extensions(self):

        return EnvironmentUIExtensionsProxy(self._client, self.space.id, self.id)

Response: Provides access to UI extensions management methods.


Instruction:
Create a Python 3 function for
deleting a personal access token.

Response:
def delete(self, token_id, *args, **kwargs):
        """
        Revokes a personal access token.
        """

        return self.client._put(
            "{0}/revoked".format(
                self._url(token_id)
            ),
            None,
            *args,
            **kwargs
        )


Instruction:
How would you code a function in Python 3 to
revoke a personal access token.

Response:
def revoke(self, token_id, *args, **kwargs):
        """
        Revokes a personal access token.
        """

        return self.delete(token_id, *args, **kwargs)


Instruction:
Write a Python 3 script to
return the base URL for the resource.

Response:
def base_url(klass, space_id='', resource_id=None, environment_id=None, **kwargs):
        """
        Returns the URI for the resource.
        """

        url = "spaces/{0}".format(
            space_id)

        if environment_id is not None:
            url = url = "{0}/environments/{1}".format(url, environment_id)

        url = "{0}/{1}".format(
            url,
            base_path_for(klass.__name__)
        )

        if resource_id:
            url = "{0}/{1}".format(url, resource_id)

        return url


Instruction:
Given the following Python 3 function, write the documentation
def create_attributes(klass, attributes, previous_object=None):

        result = {}

        if previous_object is not None:
            result = {k: v for k, v in previous_object.to_json().items() if k != 'sys'}

        result.update(attributes)

        return result

Response: Create attributes for resource creation.


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

        if attributes is None:
            attributes = {}

        headers = self.__class__.create_headers(attributes)
        headers.update(self._update_headers())

        result = self._client._put(
            self._update_url(),
            self.__class__.create_attributes(attributes, self),
            headers=headers
        )

        self._update_from_resource(result)

        return self

Response: Updates the resource with the attributes.


Instruction:
Here you have a function in Python 3, explain what it does
def to_link(self):

        link_type = self.link_type if self.type == 'Link' else self.type

        return Link({'sys': {'linkType': link_type, 'id': self.sys.get('id')}}, client=self._client)

Response: Returns a link for the resource.


Instruction:
Write a Python 3 function that can
return the JSON representation of the resource.

Response:
def to_json(self):
        """
        Returns the JSON representation of the resource.
        """

        result = {
            'sys': {}
        }
        for k, v in self.sys.items():
            if k in ['space', 'content_type', 'created_by',
                     'updated_by', 'published_by']:
                v = v.to_json()
            if k in ['created_at', 'updated_at', 'deleted_at',
                     'first_published_at', 'published_at', 'expires_at']:
                v = v.isoformat()
            result['sys'][camel_case(k)] = v

        return result


Instruction:
Create a Python 3 function for
creating the attributes for a resource creation.

Response:
def create_attributes(klass, attributes, previous_object=None):
        """
        Attributes for resource creation.
        """

        if 'fields' not in attributes:
            if previous_object is None:
                attributes['fields'] = {}
            else:
                attributes['fields'] = previous_object.to_json()['fields']
        return {'fields': attributes['fields']}


Instruction:
Make a summary of the following Python 3 code
def fields_with_locales(self):

        result = {}
        for locale, fields in self._fields.items():
            for k, v in fields.items():
                real_field_id = self._real_field_id_for(k)
                if real_field_id not in result:
                    result[real_field_id] = {}
                result[real_field_id][locale] = self._serialize_value(v)
        return result

Response: Get fields with locales per field.


Instruction:
Can you tell what is the following Python 3 function doing
def to_json(self):

        result = super(FieldsResource, self).to_json()
        result['fields'] = self.fields_with_locales()
        return result

Response: Returns the JSON Representation of the resource.


Instruction:
Write a Python 3 function for
checking if a resource has been updated since last publish.

Response:
def is_updated(self):
        """
        Checks if a resource has been updated since last publish.
        Returns False if resource has not been published before.
        """

        if not self.is_published:
            return False

        return sanitize_date(self.sys['published_at']) < sanitize_date(self.sys['updated_at'])


Instruction:
Create a Python 3 function for
resolving a link to a specific resource.

Response:
def resolve(self, space_id=None, environment_id=None):
        """
        Resolves link to a specific resource.
        """

        proxy_method = getattr(
            self._client,
            base_path_for(self.link_type)
        )
        if self.link_type == 'Space':
            return proxy_method().find(self.id)
        elif environment_id is not None:
            return proxy_method(space_id, environment_id).find(self.id)
        else:
            return proxy_method(space_id).find(self.id)


Instruction:
How would you code a function in Python 3 to
return a formatted URL for the asset s File with serialized parameters.

Response:
def url(self, **kwargs):
        """
        Returns a formatted URL for the asset's File
        with serialized parameters.

        Usage:
            >>> my_asset.url()
            "//images.contentful.com/spaces/foobar/..."
            >>> my_asset.url(w=120, h=160)
            "//images.contentful.com/spaces/foobar/...?w=120&h=160"
        """

        url = self.fields(self._locale()).get('file', {}).get('url', '')
        args = ['{0}={1}'.format(k, v) for k, v in kwargs.items()]

        if args:
            url += '?{0}'.format('&'.join(args))

        return url


Instruction:
Here you have a function in Python 3, explain what it does
def process(self):

        for locale in self._fields.keys():
            self._client._put(
                "{0}/files/{1}/process".format(
                    self.__class__.base_url(
                        self.space.id,
                        self.id,
                        environment_id=self._environment_id
                    ),
                    locale
                ),
                {},
                headers=self._update_headers()
            )
        return self.reload()

Response: Processes the asset for all locales of the asset.


Instruction:
Here you have a function in Python 3, explain what it does
def to_json(self):

        result = super(UIExtension, self).to_json()
        result.update({
            'extension': self.extension
        })

        return result

Response: Returns the JSON representation of the UI extension.


Instruction:
Here you have a function in Python 3, explain what it does
def create_attributes(klass, attributes, previous_object=None):

        return {
            'name': attributes.get(
                'name',
                previous_object.name if previous_object is not None else ''
            ),
            'description': attributes.get(
                'description',
                previous_object.description if previous_object is not None else ''
            ),
            'environments': attributes.get(
                'environments',
                [e.to_json() for e in previous_object.environments] if previous_object is not None else []  # Will default to master if empty
            )
        }

Response: Create a dictionary of attributes for a resource.


Instruction:
How would you implement a function in Python 3 that
returns the JSON representation of the API key.

Response:
def to_json(self):
        """
        Returns the JSON representation of the API key.
        """

        result = super(ApiKey, self).to_json()
        result.update({
            'name': self.name,
            'description': self.description,
            'accessToken': self.access_token,
            'environments': [e.to_json() for e in self.environments]
        })
        return result


Instruction:
Can you generate a brief explanation for the following Python 3 code
def all(self, usage_type, usage_period_id, api, query=None, *args, **kwargs):

        if query is None:
            query = {}

        mandatory_query = {
            'filters[usagePeriod]': usage_period_id,
            'filters[metric]': api
        }

        mandatory_query.update(query)

        return self.client._get(
            self._url(usage_type),
            mandatory_query,
            headers={
                'x-contentful-enable-alpha-feature': 'usage-insights'
            }
        )

Response: Gets all api usages by type for a given period an api.


Instruction:
Write a Python 3 function that can
return the base URL for the content type.

Response:
def base_url(klass, space_id, resource_id=None, public=False, environment_id=None, **kwargs):
        """
        Returns the URI for the content type.
        """

        if public:
            environment_slug = ""
            if environment_id is not None:
                environment_slug = "/environments/{0}".format(environment_id)
            return "spaces/{0}{1}/public/content_types".format(space_id, environment_slug)
        return super(ContentType, klass).base_url(
            space_id,
            resource_id=resource_id,
            environment_id=environment_id,
            **kwargs
        )


Instruction:
Can you generate a brief explanation for the following Python 3 code
def create_attributes(klass, attributes, previous_object=None):

        result = super(ContentType, klass).create_attributes(attributes, previous_object)

        if 'fields' not in result:
            result['fields'] = []
        return result

Response: Create a new object of the specified content type.


Instruction:
Can you tell what is the following Python 3 function doing
def to_json(self):

        result = super(ContentType, self).to_json()
        result.update({
            'name': self.name,
            'description': self.description,
            'displayField': self.display_field,
            'fields': [f.to_json() for f in self.fields]
        })
        return result

Response: Returns the JSON representation of the content type.


Instruction:
How would you explain what the following Python 3 function does
def entries(self):
        return ContentTypeEntriesProxy(self._client, self.space.id, self._environment_id, self.id)

Response: Provides access to entry management methods for the given content type.


Instruction:
How would you explain what the following Python 3 function does
def editor_interfaces(self):
        return ContentTypeEditorInterfacesProxy(self._client, self.space.id, self._environment_id, self.id)

Response: Provides access to editor interfaces methods for the given content type.


Instruction:
Write a Python 3 script for
providing access to snapshot management methods for the given content type.

Response:
def snapshots(self):
        """
        Provides access to snapshot management methods for the given content type.

        API reference: https://www.contentful.com/developers/docs/references/content-management-api/#/reference/snapshots/content-type-snapshots-collection

        :return: :class:`ContentTypeSnapshotsProxy <contentful_management.content_type_snapshots_proxy.ContentTypeSnapshotsProxy>` object.
        :rtype: contentful.content_type_snapshots_proxy.ContentTypeSnapshotsProxy

        Usage:

            >>> content_type_snapshots_proxy = content_type.entries()
            <ContentTypeSnapshotsProxy space_id="cfexampleapi" environment_id="master" content_type_id="cat">
        """
        return ContentTypeSnapshotsProxy(self._client, self.space.id, self._environment_id, self.id)


Instruction:
Explain what the following Python 3 code does
def base_url(klass, space_id, webhook_id, resource_id=None):

        return "spaces/{0}/webhooks/{1}/calls/{2}".format(
            space_id,
            webhook_id,
            resource_id if resource_id is not None else ''
        )

Response: Returns the base URL for the webhook call.


Instruction:
Write a Python 3 script to
attribute for space creation.

Response:
def create_attributes(klass, attributes, previous_object=None):
        """Attributes for space creation."""

        if previous_object is not None:
            return {'name': attributes.get('name', previous_object.name)}
        return {
            'name': attributes.get('name', ''),
            'defaultLocale': attributes['default_locale']
        }


Instruction:
Explain what the following Python 3 code does
def delete(self):

        return self._client._delete(
            self.__class__.base_url(
                self.sys['id']
            )
        )

Response: Deletes the object from the API.


Instruction:
Can you tell what is the following Python 3 function doing
def to_json(self):

        result = super(Space, self).to_json()
        result.update({'name': self.name})
        return result

Response: Returns the JSON representation of the space.


Instruction:
Create a Python 3 function for
getting all spaces in the system.

Response:
def all(self, query=None, **kwargs):
        """
        Gets all spaces.
        """

        return super(SpacesProxy, self).all(query=query)


Instruction:
Explain what the following Python 3 code does
def find(self, space_id, query=None, **kwargs):

        try:
            self.space_id = space_id
            return super(SpacesProxy, self).find(space_id, query=query)
        finally:
            self.space_id = None

Response: Gets a space by ID.


Instruction:
How would you implement a function in Python 3 that
creates a space with given attributes.

Response:
def create(self, attributes=None, **kwargs):
        """
        Creates a space with given attributes.
        """

        if attributes is None:
            attributes = {}
        if 'default_locale' not in attributes:
            attributes['default_locale'] = self.client.default_locale

        return super(SpacesProxy, self).create(resource_id=None, attributes=attributes)


Instruction:
Explain what the following Python 3 code does
def delete(self, space_id):

        try:
            self.space_id = space_id
            return super(SpacesProxy, self).delete(space_id)
        finally:
            self.space_id = None

Response: Deletes a space by ID.


Instruction:
Implement a Python 3 function for
providing access to editor interfaces management methods.

Response:
def editor_interfaces(self, space_id, environment_id, content_type_id):
        """
        Provides access to editor interfaces management methods.

        API reference: https://www.contentful.com/developers/docs/references/content-management-api/#/reference/editor-interface

        :return: :class:`EditorInterfacesProxy <contentful_management.editor_interfaces_proxy.EditorInterfacesProxy>` object.
        :rtype: contentful.editor_interfaces_proxy.EditorInterfacesProxy

        Usage:

            >>> editor_interfaces_proxy = client.editor_interfaces('cfexampleapi', 'master', 'cat')
            <EditorInterfacesProxy space_id="cfexampleapi" environment_id="master" content_type_id="cat">
        """

        return EditorInterfacesProxy(self, space_id, environment_id, content_type_id)


Instruction:
Create a Python 3 function to
provide access to snapshot management methods.

Response:
def snapshots(self, space_id, environment_id, resource_id, resource_kind='entries'):
        """
        Provides access to snapshot management methods.

        API reference: https://www.contentful.com/developers/docs/references/content-management-api/#/reference/snapshots

        :return: :class:`SnapshotsProxy <contentful_management.snapshots_proxy.SnapshotsProxy>` object.
        :rtype: contentful.snapshots_proxy.SnapshotsProxy

        Usage:

            >>> entry_snapshots_proxy = client.snapshots('cfexampleapi', 'master', 'nyancat')
            <SnapshotsProxy[entries] space_id="cfexampleapi" environment_id="master" parent_resource_id="nyancat">

            >>> content_type_snapshots_proxy = client.snapshots('cfexampleapi', 'master', 'cat', 'content_types')
            <SnapshotsProxy[content_types] space_id="cfexampleapi" environment_id="master" parent_resource_id="cat">
        """

        return SnapshotsProxy(self, space_id, environment_id, resource_id, resource_kind)


Instruction:
Given the following Python 3 function, write the documentation
def entry_snapshots(self, space_id, environment_id, entry_id):

        return SnapshotsProxy(self, space_id, environment_id, entry_id, 'entries')

Response: Provides access to entry snapshot management methods.


Instruction:
Can you write a function in Python 3 where it
provides access to content type snapshot management methods.

Response:
def content_type_snapshots(self, space_id, environment_id, content_type_id):
        """
        Provides access to content type snapshot management methods.

        API reference: https://www.contentful.com/developers/docs/references/content-management-api/#/reference/snapshots

        :return: :class:`SnapshotsProxy <contentful_management.snapshots_proxy.SnapshotsProxy>` object.
        :rtype: contentful.snapshots_proxy.SnapshotsProxy

        Usage:

            >>> content_type_snapshots_proxy = client.content_type_snapshots('cfexampleapi', 'master', 'cat')
            <SnapshotsProxy[content_types] space_id="cfexampleapi" environment_id="master" parent_resource_id="cat">
        """

        return SnapshotsProxy(self, space_id, environment_id, content_type_id, 'content_types')


Instruction:
Write a Python 3 script for
validating that required parameters are present.

Response:
def _validate_configuration(self):
        """
        Validates that required parameters are present.
        """

        if not self.access_token:
            raise ConfigurationException(
                'You will need to initialize a client with an Access Token'
            )
        if not self.api_url:
            raise ConfigurationException(
                'The client configuration needs to contain an API URL'
            )
        if not self.default_locale:
            raise ConfigurationException(
                'The client configuration needs to contain a Default Locale'
            )
        if not self.api_version or self.api_version < 1:
            raise ConfigurationException(
                'The API Version must be a positive number'
            )


Instruction:
Implement a Python 3 function for
setting the X - Contentful - User - Agent header.

Response:
def _contentful_user_agent(self):
        """
        Sets the X-Contentful-User-Agent header.
        """
        header = {}
        from . import __version__
        header['sdk'] = {
            'name': 'contentful-management.py',
            'version': __version__
        }
        header['app'] = {
            'name': self.application_name,
            'version': self.application_version
        }
        header['integration'] = {
            'name': self.integration_name,
            'version': self.integration_version
        }
        header['platform'] = {
            'name': 'python',
            'version': platform.python_version()
        }

        os_name = platform.system()
        if os_name == 'Darwin':
            os_name = 'macOS'
        elif not os_name or os_name == 'Java':
            os_name = None
        elif os_name and os_name not in ['macOS', 'Windows']:
            os_name = 'Linux'
        header['os'] = {
            'name': os_name,
            'version': platform.release()
        }

        def format_header(key, values):
            header = "{0} {1}".format(key, values['name'])
            if values['version'] is not None:
                header = "{0}/{1}".format(header, values['version'])
            return "{0};".format(header)

        result = []
        for k, values in header.items():
            if not values['name']:
                continue
            result.append(format_header(k, values))

        return ' '.join(result)


Instruction:
Create a Python 3 function to
create the URL for the current request.

Response:
def _url(self, url, file_upload=False):
        """
        Creates the request URL.
        """

        host = self.api_url
        if file_upload:
            host = self.uploads_api_url

        protocol = 'https' if self.https else 'http'
        if url.endswith('/'):
            url = url[:-1]
        return '{0}://{1}/{2}'.format(
            protocol,
            host,
            url
        )


Instruction:
Can you implement a function in Python 3 that
performs the HTTP request.

Response:
def _http_request(self, method, url, request_kwargs=None):
        """
        Performs the requested HTTP request.
        """

        kwargs = request_kwargs if request_kwargs is not None else {}

        headers = self._request_headers()
        headers.update(self.additional_headers)
        if 'headers' in kwargs:
            headers.update(kwargs['headers'])
        kwargs['headers'] = headers

        if self._has_proxy():
            kwargs['proxies'] = self._proxy_parameters()

        request_url = self._url(
            url,
            file_upload=kwargs.pop('file_upload', False)
        )

        request_method = getattr(requests, method)
        response = request_method(request_url, **kwargs)

        if response.status_code == 429:
            raise RateLimitExceededError(response)

        return response


Instruction:
Can you create a Python 3 function that
performs the HTTP GET request.

Response:
def _http_get(self, url, query, **kwargs):
        """
        Performs the HTTP GET request.
        """

        self._normalize_query(query)

        kwargs.update({'params': query})

        return self._http_request('get', url, kwargs)


Instruction:
Can you tell what is the following Python 3 function doing
def _http_post(self, url, data, **kwargs):

        if not kwargs.get('file_upload', False):
            data = json.dumps(data)

        kwargs.update({'data': data})

        return self._http_request('post', url, kwargs)

Response: Performs the HTTP POST request.


Instruction:
How would you code a function in Python 3 to
perform the HTTP PUT request.

Response:
def _http_put(self, url, data, **kwargs):
        """
        Performs the HTTP PUT request.
        """

        kwargs.update({'data': json.dumps(data)})

        return self._http_request('put', url, kwargs)


Instruction:
Explain what the following Python 3 code does
def _request(self, method, url, query_or_data=None, **kwargs):

        if query_or_data is None:
            query_or_data = {}

        request_method = getattr(self, '_http_{0}'.format(method))
        response = retry_request(self)(request_method)(url, query_or_data, **kwargs)

        if self.raw_mode:
            return response

        if response.status_code >= 300:
            error = get_error(response)
            if self.raise_errors:
                raise error
            return error

        # Return response object on NoContent
        if response.status_code == 204 or not response.text:
            return response

        return ResourceBuilder(
            self,
            self.default_locale,
            response.json()
        ).build()

Response: Wrapper for the HTTP requests and return the response object on success.


Instruction:
Can you generate the documentation for the following Python 3 function
def _get(self, url, query=None, **kwargs):

        return self._request('get', url, query, **kwargs)

Response: Wrapper for the HTTP GET request.


Instruction:
Given the following Python 3 function, write the documentation
def _post(self, url, attributes=None, **kwargs):

        return self._request('post', url, attributes, **kwargs)

Response: Wrapper for the HTTP POST request.


Instruction:
Can you write a function in Python 3 where it
wraps for the HTTP PUT request.

Response:
def _put(self, url, attributes=None, **kwargs):
        """
        Wrapper for the HTTP PUT request.
        """

        return self._request('put', url, attributes, **kwargs)


Instruction:
How would you code a function in Python 3 to
wrap for the HTTP DELETE request.

Response:
def _delete(self, url, **kwargs):
        """
        Wrapper for the HTTP DELETE request.
        """

        response = retry_request(self)(self._http_delete)(url, **kwargs)

        if self.raw_mode:
            return response

        if response.status_code >= 300:
            error = get_error(response)
            if self.raise_errors:
                raise error
            return error

        return response


Instruction:
Given the following Python 3 function, write the documentation
def to_json(self):

        result = super(Locale, self).to_json()
        result.update({
            'code': self.code,
            'name': self.name,
            'fallbackCode': self.fallback_code,
            'optional': self.optional,
            'contentDeliveryApi': self.content_delivery_api,
            'contentManagementApi': self.content_management_api
        })
        return result

Response: Returns the JSON representation of the locale.


Instruction:
Can you create a Python 3 function that
gets all assets of a space.

Response:
def all(self, query=None, **kwargs):
        """
        Gets all assets of a space.
        """

        if query is None:
            query = {}

        normalize_select(query)

        return super(AssetsProxy, self).all(query, **kwargs)


Instruction:
How would you explain what the following Python 3 function does
def find(self, asset_id, query=None, **kwargs):

        if query is None:
            query = {}

        normalize_select(query)

        return super(AssetsProxy, self).find(asset_id, query=query, **kwargs)

Response: Gets a single asset by ID.


Instruction:
Make a summary of the following Python 3 code
def snapshots(self):
        return EntrySnapshotsProxy(self._client, self.sys['space'].id, self._environment_id, self.sys['id'])

Response: Provides access to snapshot management methods for the given entry.


Instruction:
Write a Python 3 function for
updating the entry with attributes.

Response:
def update(self, attributes=None):
        """
        Updates the entry with attributes.
        """

        if attributes is None:
            attributes = {}

        attributes['content_type_id'] = self.sys['content_type'].id

        return super(Entry, self).update(attributes)


Instruction:
Here you have a function in Python 3, explain what it does
def all(self, query=None):

        if query is None:
            query = {}
        return self.client._get(
            self._url(),
            query
        )

Response: Gets all the resource collections for this resource class.


Instruction:
How would you explain what the following Python 3 function does
def find(self, resource_id, query=None, **kwargs):

        if query is None:
            query = {}
        return self.client._get(
            self._url(resource_id),
            query,
            **kwargs
        )

Response: Gets a single resource.


Instruction:
Explain what the following Python 3 code does
def create(self, resource_id=None, attributes=None):

        if attributes is None:
            attributes = {}

        result = None
        if not resource_id:
            result = self.client._post(
                self._url(resource_id),
                self._resource_class.create_attributes(attributes),
                headers=self._resource_class.create_headers(attributes)
            )
        else:
            result = self.client._put(
                self._url(resource_id),
                self._resource_class.create_attributes(attributes),
                headers=self._resource_class.create_headers(attributes)
            )

        return result

Response: Creates a resource with the given ID and attributes.


Instruction:
Make a summary of the following Python 3 code
def delete(self, resource_id, **kwargs):

        return self.client._delete(self._url(resource_id), **kwargs)

Response: Deletes a resource by ID.


Instruction:
Make a summary of the following Python 3 code
def to_json(self):

        result = super(Role, self).to_json()
        result.update({
            'name': self.name,
            'description': self.description,
            'permissions': self.permissions,
            'policies': self.policies
        })
        return result

Response: Returns the JSON representation of the role.


Instruction:
Can you implement a function in Python 3 that
returns the JSON representation of the space membership.

Response:
def to_json(self):
        """
        Returns the JSON representation of the space membership.
        """

        result = super(SpaceMembership, self).to_json()
        result.update({
            'admin': self.admin,
            'roles': self.roles
        })
        return result


Instruction:
Can you generate the documentation for the following Python 3 function
def create(self, file_or_path, **kwargs):

        opened = False
        if isinstance(file_or_path, str_type()):
            file_or_path = open(file_or_path, 'rb')
            opened = True
        elif not getattr(file_or_path, 'read', False):
            raise Exception("A file or path to a file is required for this operation.")

        try:
            return self.client._post(
                self._url(),
                file_or_path,
                headers=self._resource_class.create_headers({}),
                file_upload=True
            )
        finally:
            if opened:
                file_or_path.close()

Response: Creates an upload for the given file or path.


Instruction:
Can you create a Python 3 function that
finds an upload by ID.

Response:
def find(self, upload_id, **kwargs):
        """
        Finds an upload by ID.
        """

        return super(UploadsProxy, self).find(upload_id, file_upload=True)


Instruction:
Write a Python 3 script to
delete an upload by ID.

Response:
def delete(self, upload_id):
        """
        Deletes an upload by ID.
        """

        return super(UploadsProxy, self).delete(upload_id, file_upload=True)


Instruction:
Can you write a function in Python 3 where it
returns the JSON representation of the content type field.

Response:
def to_json(self):
        """
        Returns the JSON Representation of the content type field.
        """

        result = {
            'name': self.name,
            'id': self._real_id(),
            'type': self.type,
            'localized': self.localized,
            'omitted': self.omitted,
            'required': self.required,
            'disabled': self.disabled,
            'validations': [v.to_json() for v in self.validations]
        }

        if self.type == 'Array':
            result['items'] = self.items

        if self.type == 'Link':
            result['linkType'] = self.link_type

        return result


Instruction:
Write a Python 3 function for
coercing value to location hash.

Response:
def coerce(self, value):
        """
        Coerces value to location hash.
        """

        return {
            'lat': float(value.get('lat', value.get('latitude'))),
            'lon': float(value.get('lon', value.get('longitude')))
        }


Instruction:
How would you code a function in Python 3 to
return the base URL for the snapshot.

Response:
def base_url(klass, space_id, parent_resource_id, resource_url='entries', resource_id=None, environment_id=None):
        """
        Returns the URI for the snapshot.
        """

        return "spaces/{0}{1}/{2}/{3}/snapshots/{4}".format(
            space_id,
            '/environments/{0}'.format(environment_id) if environment_id is not None else '',
            resource_url,
            parent_resource_id,
            resource_id if resource_id is not None else ''
        )


Instruction:
Explain what the following Python 3 code does
def to_json(self):

        result = super(Snapshot, self).to_json()
        result.update({
            'snapshot': self.snapshot.to_json(),
        })
        return result

Response: Returns the JSON representation of the snapshot.


Instruction:
Given the following Python 3 function, write the documentation
def all(self, *args, **kwargs):

        return self.client._get(
            self._url(),
            {},
            headers={
                'x-contentful-enable-alpha-feature': 'usage-insights'
            }
        )

Response: Gets all usage periods.


Instruction:
Write a Python 3 script to
create attributes for webhook creation.

Response:
def create_attributes(klass, attributes, previous_object=None):
        """
        Attributes for webhook creation.
        """

        result = super(Webhook, klass).create_attributes(attributes, previous_object)

        if 'topics' not in result:
            raise Exception("Topics ('topics') must be provided for this operation.")
        return result


Instruction:
Can you write a function in Python 3 where it
provides access to call overview for the given webhook.

Response:
def calls(self):
        """
        Provides access to call overview for the given webhook.

        API reference: https://www.contentful.com/developers/docs/references/content-management-api/#/reference/webhook-calls

        :return: :class:`WebhookWebhooksCallProxy <contentful_management.webhook_webhooks_call_proxy.WebhookWebhooksCallProxy>` object.
        :rtype: contentful.webhook_webhooks_call_proxy.WebhookWebhooksCallProxy

        Usage:

            >>> webhook_webhooks_call_proxy = webhook.calls()
            <WebhookWebhooksCallProxy space_id="cfexampleapi" webhook_id="my_webhook">
        """
        return WebhookWebhooksCallProxy(self._client, self.sys['space'].id, self.sys['id'])


Instruction:
Here you have a function in Python 3, explain what it does
def health(self):
        return WebhookWebhooksHealthProxy(self._client, self.sys['space'].id, self.sys['id'])

Response: Provides access to health overview for the given webhook.


Instruction:
Can you tell what is the following Python 3 function doing
def to_json(self):

        result = super(Webhook, self).to_json()
        result.update({
            'name': self.name,
            'url': self.url,
            'topics': self.topics,
            'httpBasicUsername': self.http_basic_username,
            'headers': self.headers
        })

        if self.filters:
            result.update({'filters': self.filters})

        if self.transformation:
            result.update({'transformation': self.transformation})

        return result

Response: Returns the JSON representation of the webhook.


Instruction:
Make a summary of the following Python 3 code
def base_url(self, space_id, content_type_id, environment_id=None, **kwargs):

        return "spaces/{0}{1}/content_types/{2}/editor_interface".format(
            space_id,
            '/environments/{0}'.format(environment_id) if environment_id is not None else '',
            content_type_id
        )

Response: Returns the URI for the editor interface.


Instruction:
Explain what the following Python 3 code does
def to_json(self):

        result = super(EditorInterface, self).to_json()
        result.update({'controls': self.controls})
        return result

Response: Returns the JSON representation of the editor interface.


Instruction:
How would you implement a function in Python 3 that
returns the JSON representation of the content type field validation.

Response:
def to_json(self):
        """
        Returns the JSON Representation of the content type field validation.
        """

        result = {}
        for k, v in self._data.items():
            result[camel_case(k)] = v
        return result


Instruction:
Implement a Python 3 function for
building the object from the JSON response.

Response:
def build(self):
        """
        Creates the objects from the JSON response.
        """

        if self.json['sys']['type'] == 'Array':
            return self._build_array()
        return self._build_item(self.json)


Instruction:
Can you generate a brief explanation for the following Python 3 code
def create(self, resource_id=None, attributes=None):

        return self.proxy.create(resource_id=resource_id, attributes=attributes)

Response: Creates a resource with a given ID and attributes.


Instruction:
Can you write a function in Python 3 where it
finds a single resource by ID related to the current space.

Response:
def find(self, resource_id, query=None):
        """
        Finds a single resource by ID related to the current space.
        """

        return self.proxy.find(resource_id, query=query)


Instruction:
How would you explain what the following Python 3 function does
def get_ngroups(self, field=None):
        '''
        Returns ngroups count if it was specified in the query, otherwise ValueError.

        If grouping on more than one field, provide the field argument to specify which count you are looking for.
        '''
        field = field if field else self._determine_group_field(field)
        if 'ngroups' in self.data['grouped'][field]:
            return self.data['grouped'][field]['ngroups']
        raise ValueError("ngroups not found in response. specify group.ngroups in the query.")

Response: Returns the number of groups in the current resource.


Instruction:
Explain what the following Python 3 code does
def get_groups_count(self, field=None):
        '''
        Returns 'matches' from group response.

                If grouping on more than one field, provide the field argument to specify which count you are looking for.
        '''
        field = field if field else self._determine_group_field(field)
        if 'matches' in self.data['grouped'][field]:
            return self.data['grouped'][field]['matches']
        raise ValueError("group matches not found in response")

Response: Returns the number of matches in the group response.


Instruction:
How would you code a function in Python 3 to
flatten the group response and just returns a list of documents.

Response:
def get_flat_groups(self, field=None):
        '''
        Flattens the group response and just returns a list of documents.
        '''
        field = field if field else self._determine_group_field(field)
        temp_groups = self.data['grouped'][field]['groups']
        return [y for x in temp_groups for y in x['doclist']['docs']]


Instruction:
Write a Python 3 script to
return a dictionary of facets for the current locale.

Response:
def get_facets(self):
        '''
        Returns a dictionary of facets::

            >>> res = solr.query('SolrClient_unittest',{
                    'q':'product_name:Lorem',
                    'facet':True,
                    'facet.field':'facet_test',
            })... ... ... ...
            >>> res.get_results_count()
            4
            >>> res.get_facets()
            {'facet_test': {'ipsum': 0, 'sit': 0, 'dolor': 2, 'amet,': 1, 'Lorem': 1}}

        '''
        if not hasattr(self,'facets'):
            self.facets = {}
            data = self.data
            if 'facet_counts' in data.keys() and type(data['facet_counts']) == dict:
                if 'facet_fields' in data['facet_counts'].keys() and type(data['facet_counts']['facet_fields']) == dict:
                    for facetfield in data['facet_counts']['facet_fields']:
                        if type(data['facet_counts']['facet_fields'][facetfield] == list):
                            l = data['facet_counts']['facet_fields'][facetfield]
                            self.facets[facetfield] = OrderedDict(zip(l[::2],l[1::2]))
                return self.facets
            else:
                raise SolrResponseError("No Facet Information in the Response")
        else:
            return self.facets


Instruction:
How would you code a function in Python 3 to
return query facet ranges

Response:
def get_facets_ranges(self):
        '''
        Returns query facet ranges ::

            >>> res = solr.query('SolrClient_unittest',{
                'q':'*:*',
                'facet':True,
                'facet.range':'price',
                'facet.range.start':0,
                'facet.range.end':100,
                'facet.range.gap':10
                })
            >>> res.get_facets_ranges()
            {'price': {'80': 9, '10': 5, '50': 3, '20': 7, '90': 3, '70': 4, '60': 7, '0': 3, '40': 5, '30': 4}}

        '''
        if not hasattr(self,'facet_ranges'):
            self.facet_ranges = {}
            data = self.data
            if 'facet_counts' in data.keys() and type(data['facet_counts']) == dict:
                if 'facet_ranges' in data['facet_counts'].keys() and type(data['facet_counts']['facet_ranges']) == dict:
                    for facetfield in data['facet_counts']['facet_ranges']:
                        if type(data['facet_counts']['facet_ranges'][facetfield]['counts']) == list:
                            l = data['facet_counts']['facet_ranges'][facetfield]['counts']
                            self.facet_ranges[facetfield] = OrderedDict(zip(l[::2],l[1::2]))
                    return self.facet_ranges
            else:
                raise SolrResponseError("No Facet Ranges in the Response")
        else:
            return self.facet_ranges


Instruction:
How would you implement a function in Python 3 that
parses facet pivot response. Example :: returns a dict of facet pivot field names and values.

Response:
def get_facet_pivot(self):
        '''
        Parses facet pivot response. Example::
            >>> res = solr.query('SolrClient_unittest',{
            'q':'*:*',
            'fq':'price:[50 TO *]',
            'facet':True,
            'facet.pivot':'facet_test,price' #Note how there is no space between fields. They are just separated by commas
            })
            >>> res.get_facet_pivot()
            {'facet_test,price': {'Lorem': {89: 1, 75: 1}, 'ipsum': {53: 1, 70: 1, 55: 1, 89: 1, 74: 1, 93: 1, 79: 1}, 'dolor': {61: 1, 94: 1}, 'sit': {99: 1, 50: 1, 67: 1, 52: 1, 54: 1, 71: 1, 72: 1, 84: 1, 62: 1}, 'amet,': {68: 1}}}

        This method has built in recursion and can support indefinite number of facets. However, note that the output format is significantly massaged since Solr by default outputs a list of fields in each pivot field.
        '''
        if not hasattr(self,'facet_pivot'):
            self.facet_pivot = {}
            if 'facet_counts' in self.data.keys():
                pivots = self.data['facet_counts']['facet_pivot']
                for fieldset in pivots:
                    self.facet_pivot[fieldset] = {}
                    for sub_field_set in pivots[fieldset]:
                        res = self._rec_subfield(sub_field_set)
                        self.facet_pivot[fieldset].update(res)
                return self.facet_pivot
        else:
            return self.facet_pivot


Instruction:
Can you write a function in Python 3 where it
returns all values of the given field in the database as a list.

Response:
def get_field_values_as_list(self,field):
        '''
        :param str field: The name of the field for which to pull in values.
        Will parse the query results (must be ungrouped) and return all values of 'field' as a list. Note that these are not unique values.  Example::

            >>> r.get_field_values_as_list('product_name_exact')
            ['Mauris risus risus lacus. sit', 'dolor auctor Vivamus fringilla. vulputate', 'semper nisi lacus nulla sed', 'vel amet diam sed posuere', 'vitae neque ultricies, Phasellus ac', 'consectetur nisi orci, eu diam', 'sapien, nisi accumsan accumsan In', 'ligula. odio ipsum sit vel', 'tempus orci. elit, Ut nisl.', 'neque nisi Integer nisi Lorem']

        '''
        return [doc[field] for doc in self.docs if field in doc]


Instruction:
How would you explain what the following Python 3 function does
def get_first_field_values_as_list(self, field):
        '''
        :param str field: The name of the field for lookup.

        Goes through all documents returned looking for specified field. At first encounter will return the field's value.
        '''
        for doc in self.docs:
            if field in doc.keys():
                return doc[field]
        raise SolrResponseError("No field in result set")

Response: Returns the first value of a field in the result set.


Instruction:
Given the following Python 3 function, write the documentation
def get_facet_values_as_list(self, field):
        '''
        :param str field: Name of facet field to retrieve values from.

        Returns facet values as list for a given field. Example::

            >>> res = solr.query('SolrClient_unittest',{
                'q':'*:*',
                'facet':'true',
                'facet.field':'facet_test',
            })
            >>> res.get_facet_values_as_list('facet_test')
            [9, 6, 14, 10, 11]
            >>> res.get_facets()
            {'facet_test': {'Lorem': 9, 'ipsum': 6, 'amet,': 14, 'dolor': 10, 'sit': 11}}

        '''
        facets = self.get_facets()
        out = []
        if field in facets.keys():
            for facetfield in facets[field]:
                out.append(facets[field][facetfield])
            return out
        else:
            raise SolrResponseError("No field in facet output")

Response: Returns facet values as list for a given field.


Instruction:
Can you write a function in Python 3 where it
returns the list of keys from the facet field.

Response:
def get_facet_keys_as_list(self,field):
        '''
        :param str field: Name of facet field to retrieve keys from.

        Similar to get_facet_values_as_list but returns the list of keys as a list instead.
        Example::

            >>> r.get_facet_keys_as_list('facet_test')
            ['Lorem', 'ipsum', 'amet,', 'dolor', 'sit']

        '''
        facets = self.get_facets()
        if facets == -1:
            return facets
        if field in facets.keys():
            return [x for x in facets[field]]


Instruction:
Write a Python 3 script to
get the json. fact output of the resource.

Response:
def json_facet(self, field=None):
        '''
        EXPERIMENTAL

        Tried to kick back the json.fact output.
        '''
        facets = self.data['facets']
        if field is None:
            temp_fields = [x for x in facets.keys() if x != 'count']
            if len(temp_fields) != 1:
                raise ValueError("field argument not specified and it looks like there is more than one field in facets. Specify the field to get json.facet from. ")
            field = temp_fields[0]

        if field not in self.data['facets']:
            raise ValueError("Facet Field {} Not found in response, available fields are {}".format(
                                        field, self.data['facets'].keys() ))
        return self.data['facets'][field]


Instruction:
Write a Python 3 function for
returning a dictionary that is easier to work with the count of the facets and returns then as a dictionary that is easier to work with the base class.

Response:
def get_jsonfacet_counts_as_dict(self, field, data=None):
        '''
        EXPERIMENTAL
        Takes facets and returns then as a dictionary that is easier to work with,
        for example, if you are getting something this::

            {'facets': {'count': 50,
              'test': {'buckets': [{'count': 10,
                 'pr': {'buckets': [{'count': 2, 'unique': 1, 'val': 79},
                   {'count': 1, 'unique': 1, 'val': 9}]},
                 'pr_sum': 639.0,
                 'val': 'consectetur'},
                {'count': 8,
                 'pr': {'buckets': [{'count': 1, 'unique': 1, 'val': 9},
                   {'count': 1, 'unique': 1, 'val': 31},
                   {'count': 1, 'unique': 1, 'val': 33}]},
                 'pr_sum': 420.0,
                 'val': 'auctor'},
                {'count': 8,
                 'pr': {'buckets': [{'count': 2, 'unique': 1, 'val': 94},
                   {'count': 1, 'unique': 1, 'val': 25}]},
                 'pr_sum': 501.0,
                 'val': 'nulla'}]}}}

        This should return you something like this::

            {'test': {'auctor': {'count': 8,
                                 'pr': {9: {'count': 1, 'unique': 1},
                                        31: {'count': 1, 'unique': 1},
                                        33: {'count': 1, 'unique': 1}},
                                 'pr_sum': 420.0},
                      'consectetur': {'count': 10,
                                      'pr': {9: {'count': 1, 'unique': 1},
                                             79: {'count': 2, 'unique': 1}},
                                      'pr_sum': 639.0},
                      'nulla': {'count': 8,
                                'pr': {25: {'count': 1, 'unique': 1},
                                       94: {'count': 2, 'unique': 1}},
                                'pr_sum': 501.0}}}
        '''
        data = data if data else self.data['facets']
        if field not in data:
            raise ValueError("Field To start Faceting on not specified.")
        out = { field: self._json_rec_dict(data[field]['buckets']) }
        return out


Instruction:
Write a Python 3 function that can
generate a random file name based on self. _output_filename_pattern for the output to do file.

Response:
def _gen_file_name(self):
        '''
        Generates a random file name based on self._output_filename_pattern for the output to do file.
        '''
        date = datetime.datetime.now()
        dt = "{}-{}-{}-{}-{}-{}-{}".format(str(date.year),str(date.month),str(date.day),str(date.hour),str(date.minute),str(date.second),str(random.randint(0,10000)))
        return self._output_filename_pattern.format(dt)


Instruction:
Can you tell what is the following Python 3 function doing
def add(self, item=None, finalize=False, callback=None):
        '''
        Takes a string, dictionary or list of items for adding to queue. To help troubleshoot it will output the updated buffer size, however when the content gets written it will output the file path of the new file. Generally this can be safely discarded.

        :param <dict,list> item: Item to add to the queue. If dict will be converted directly to a list and then to json. List must be a list of dictionaries. If a string is submitted, it will be written out as-is immediately and not buffered.
        :param bool finalize: If items are buffered internally, it will flush them to disk and return the file name.
        :param callback: A callback function that will be called when the item gets written to disk. It will be passed one position argument, the file path of the file written. Note that errors from the callback method will not be re-raised here.
        '''
        if item:
            if type(item) is list:
                check = list(set([type(d) for d in item]))
                if len(check) > 1 or dict not in check:
                    raise ValueError("More than one data type detected in item (list). Make sure they are all dicts of data going to Solr")
            elif type(item) is dict:
                item = [item]
            elif type(item) is str:
                return self._write_file(item)
            else:
                raise ValueError("Not the right data submitted. Make sure you are sending a dict or list of dicts")
        with self._rlock:
            res = self._preprocess(item, finalize, callback)
        return res

Response: Adds a new item to the queue.


Instruction:
Explain what the following Python 3 code does
def _lock(self):
        '''
        Locks, or returns False if already locked
        '''
        if not self._is_locked():
            with open(self._lck,'w') as fh:
                if self._devel: self.logger.debug("Locking")
                fh.write(str(os.getpid()))
            return True
        else:
            return False

Response: Locks the current user s log file. Returns True if the lock was successful False if the lock was already acquired.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def _is_locked(self):
        '''
        Checks to see if we are already pulling items from the queue
        '''
        if os.path.isfile(self._lck):
            try:
                import psutil
            except ImportError:
                return True #Lock file exists and no psutil
            #If psutil is imported
            with open(self._lck) as f:
                pid = f.read()
            return True if psutil.pid_exists(int(pid)) else False
        else:
            return False

Response: Checks to see if we are already pulling items from the queue