<commit_before># -*- coding: utf-8 -*-
from abc import ABCMeta, abstractmethod


class ABCParticles(object):
    """Abstract base class for a container of particles items.

    Attributes
    ----------
    name : str
        name of particles item.
    data : DataContainer
        The data associated with the container

    """
    __metaclass__ = ABCMeta

    @abstractmethod
    def add_particle(self, particle):
        """Adds the particle to the container.

        If the new particle has no uid, the particle container
        will generate a new uid for it. If the particle has
        already an uid, it won't add the particle if a particle
        with the same uid already exists. If the user wants to replace
        an existing particle in the container there is an 'update_particle'
        method for that purpose.

        Parameters
        ----------
        particle : Particle
            the new particle that will be included in the container.

        Returns
        -------
        uid : uuid.UUID
            The uid of the added particle.

        Raises
        ------
        ValueError :
            when the new particle already exists in the container.

        Examples
        --------
        Add a particle to a Particles container.

        >>> particle = Particle()
        >>> particles = Particles(name="foo")
        >>> particles.add_particle(part)

        """

    @abstractmethod
    def add_bond(self, bond):
        """Adds the bond to the container.

        Also like with particles, if the bond has a defined uid,
        it won't add the bond if a bond with the same uid already exists, and
        if the bond has no uid the particle container will generate an
        uid. If the user wants to replace an existing bond in the
        container there is an 'update_bond' method for that purpose.

        Parameters
        ----------
        bond : Bond
            the new bond that will be included in the container.

        Returns
        -------
        uid : uuid.UID
            The uid of the added bond.

        Raises
        ------
        ValueError :
            When the new particle already exists in the container.

        Examples
        --------
        Add a bond to a Particles container.

        >>> bond = Bond()
        >>> particles = Particles(name="foo")
        >>> particles.add_bond(bond)

        """

    @abstractmethod
    def update_particle(self, particle):
        """Replaces an existing particle.

        Takes the uid of 'particle' and searches inside the container for
        that particle. If the particle exists, it is replaced with the new
        particle passed as parameter. If the particle doesn't exist, it will
        raise an exception.

        Parameters
        ----------

        particle : Particle
            the particle that will be replaced.

        Raises
        ------
        ValueError :
            If the particle does not exist.

        Examples
        --------
        Given a Particle that already exists in the Particles container
        (taken with the 'get_particle' method for example), just call the
        function passing the Particle as parameter.

        >>> part_container = Particles(name="foo")
        >>> ...
        >>> part = part_container.get_particle(uid)
        >>> ... #do whatever you want with the particle
        >>> part_container.update_particle(part)

        """

    @abstractmethod
    def update_bond(self, bond):
        """Replaces an existing bond.

        Takes the uid of 'bond' and searches inside the container for
        that bond. If the bond exists, it is replaced with the new
        bond passed as parameter. If the bond doesn't exist, it will
        raise an exception.

        Parameters
        ----------
        bond : Bond
            the bond that will be replaced.

        Raises
        ------
        ValueError :
            If the bond doesn't exist.

        Examples
        --------
        Given a Bond that already exists in the Particles container
        (taken with the 'get_bond' method for example) just call the
        function passing the Bond as parameter.

        >>> particles = Particles(name="foo")
        >>> ...
        >>> bond = particles.get_bond(uid)
        >>> ... #do whatever you want with the bond
        >>> particles.update_bond(bond)

        """

    @abstractmethod
    def get_particle(self, uid):
        """Returns a copy of the particle with the 'particle_id' id.

        Parameters
        ----------

        uid : uuid.UUID
            the uid of the particle

        Raises
        ------
        KeyError :
           when the particle is not in the container.

        Returns
        -------
        particle : Particle
            A copy of the internally stored particle info.

        """

    @abstractmethod
    def get_bond(self, uid):
        """Returns a copy of the bond with the 'bond_id' id.

        Parameters
        ----------
        uid : uuid.UUID
            the uid of the bond

        Raises
        ------
        KeyError :
           when the bond is not in the container.

        Returns
        -------
        bond : Bond
            A copy of the internally stored bond info.

        """

    @abstractmethod
    def remove_particle(self, uid):
        """Removes the particle with uid from the container.

        The uid passed as parameter should exists in the container. Otherwise
        an exception will be raised.

        Parameters
        ----------
        uid : uuid.UUID
            the uid of the particle to be removed.

        Raises
        ------
        KeyError :
           If the particle doesn't exist.


        Examples
        --------
        Having an uid of an existing particle, pass it to the function.

        >>> particles = Particles(name="foo")
        >>> ...
        >>> particle = particles.get_particle(uid)
        >>> ...
        >>> particles.remove_particle(part.uid)
        or directly
        >>> particles.remove_particle(uid)

        """

    @abstractmethod
    def remove_bond(self, uid):
        """Removes the bond with the uid from the container.

        The uid passed as parameter should exists in the container. If
        it doesn't exists, nothing will happen.

        Parameters
        ----------
        uid : uuid.UUID
            the uid of the bond to be removed.

        Examples
        --------
        Having an uid of an existing bond, pass it to the function.

        >>> particles = Particles(name="foo")
        >>> ...
        >>> bond = particles.get_bond(uid)
        >>> ...
        >>> particles.remove_bond(bond.uid)
        or
        >>> particles.remove_bond(uid)
<commit_msg>Modified abstract class.<commit_after># -*- coding: utf-8 -*-
from abc import ABCMeta, abstractmethod


class ABCParticles(object):
    """Abstract base class for a container of particles items.

    Attributes
    ----------
    name : str
        name of particles item.
    data : DataContainer
        The data associated with the container

    """
    __metaclass__ = ABCMeta

    @abstractmethod
    def add_particles(self, iterable):
        """Adds a set of particles from the provided iterable
        to the container.

        If any particle have no uids, the container
        will generate a new uids for it. If the particle has
        already an uids, it won't add the particle if a particle
        with the same uid already exists. If the user wants to replace
        an existing particle in the container there is an 'update_particles'
        method for that purpose.

        Parameters
        ----------
        iterable : iterable of Particle objects
            the new set of particles that will be included in the container.

        Returns
        -------
        uids : list of uuid.UUID
            The uids of the added particles.

        Raises
        ------
        ValueError :
            when there is a particle with an uids that already exists in the container.

        Examples
        --------
        Add a set of particles to a Particles container.

        >>> particle_list = [Particle(), Particle()]
        >>> particles = Particles(name="foo")
        >>> uids = particles.add_particles(particle_list)

        """

    @abstractmethod
    def add_bonds(self, iterable):
        """Adds a set of bonds to the container.

        Also like with particles, if any bond has a defined uid,
        it won't add the bond if a bond with the same uid already exists, and
        if the bond has no uid the particle container will generate an
        uid. If the user wants to replace an existing bond in the
        container there is an 'update_bonds' method for that purpose.

        Parameters
        ----------
        iterable : iterable of Bond objects
            the new bond that will be included in the container.

        Returns
        -------
        uuid : list of uuid.UUID
            The uuids of the added bonds.

        Raises
        ------
        ValueError :
            when there is a bond with an uuid that already exists in the container.

        Examples
        --------
        Add a set of bonds to a Particles container.

        >>> bonds_list = [Bond(), Bond()]
        >>> particles = Particles(name="foo")
        >>> particles.add_bond(bonds_list)

        """

    @abstractmethod
    def update_particles(self, iterable):
        """Updates a set of particles from the provided iterable.

        Takes the uids of the particles and searches inside the container for
        those particles. If the particles exists, they are replaced in the container.
        If any particle doesn't exist, it will raise an exception.

        Parameters
        ----------

        iterable : iterable of Particle objects
            the particles that will be replaced.

        Raises
        ------
        ValueError :
            If any particle inside the iterable does not exist.

        Examples
        --------
        Given a set of Particle objects that already exists in the Particles container
        (taken with the 'get_particle' method for example), just call the
        function passing the Particle items as parameter.

        >>> part_container = Particles(name="foo")
        >>> ...
        >>> part1 = part_container.get_particle(uid1)
        >>> part2 = part_container.get_particle(uid2)
        >>> ... #do whatever you want with the particles
        >>> part_container.update_particle([part1, part2])

        """

    @abstractmethod
    def update_bonds(self, iterable):
        """Updates a set of bonds from the provided iterable.

        Takes the uids of the bonds and searches inside the container for
        those bond. If the bonds exists, they are replaced in the container.
        If any bond doesn't exist, it will raise an exception.

        Parameters
        ----------
        iterable : iterable of Bond objects
            the bonds that will be replaced.

        Raises
        ------
        ValueError :
            If any bond doesn't exist.

        Examples
        --------
        Given a set of Bond objects that already exists in the Particles container
        (taken with the 'get_bond' method for example) just call the
        function passing the set of Bond as parameter.

        >>> particles = Particles(name="foo")
        >>> ...
        >>> bond1 = particles.get_bond(uid1)
        >>> bond2 = particles.get_bond(uid2)
        >>> ... #do whatever you want with the bonds
        >>> particles.update_bond([bond1, bond2])

        """

    @abstractmethod
    def get_particle(self, uid):
        """Returns a copy of the particle with the 'particle_id' id.

        Parameters
        ----------

        uid : uuid.UUID
            the uid of the particle

        Raises
        ------
        KeyError :
           when the particle is not in the container.

        Returns
        -------
        particle : Particle
            A copy of the internally stored particle info.

        """

    @abstractmethod
    def get_bond(self, uid):
        """Returns a copy of the bond with the 'bond_id' id.

        Parameters
        ----------
        uid : uuid.UUID
            the uid of the bond

        Raises
        ------
        KeyError :
           when the bond is not in the container.

        Returns
        -------
        bond : Bond
            A copy of the internally stored bond info.

        """

    @abstractmethod
    def remove_particles(self, uids):
        """Remove the particles with the provided uids from the container.

        The uids inside the iterable should exists in the container. Otherwise
        an exception will be raised.

        Parameters
        ----------
        uid : uuid.UUID
            the uid of the particle to be removed.

        Raises
        ------
        KeyError :
           If any particle doesn't exist.


        Examples
        --------
        Having a set of uids of existing particles, pass it to the method.

        >>> particles = Particles(name="foo")
        >>> ...
        >>> particle1 = particles.get_particle(uid1)
        >>> particle2 = particles.get_particle(uid2)
        >>> ...
        >>> particles.remove_particle([part1.uid, part2.uid)
        or directly
        >>> particles.remove_particle([uid1, uid2])

        """

    @abstractmethod
    def remove_bonds(self, uids):
        """Remove the bonds with the provided uids.

        The uids passed as parameter should exists in the container. If
        any uid doesn't exist, an exception will be raised.

        Parameters
        ----------
        uids : uuid.UUID
            the uid of the bond to be removed.

        Examples
        --------
        Having a set of uids of existing bonds, pass it to the method.

        >>> particles = Particles(name="foo")
        >>> ...
        >>> bond1 = particles.get_bond(uid1)
        >>> bond2 = particles.get_bond(uid2)
        >>> ...
        >>> particles.remove_bonds([bond1.uid, bond2.uid])
        or
        >>> particles.remove_bond([uid1, uid2])

{'fraction_non_alphanumeric': 0.0921089779785432, 'fraction_numerical': 0.0021174477696216825, 'mean_word_length': 1.6060327386426339, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 183, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3085114', 'n_tokens_mistral': 3506, 'n_tokens_neox': 3339, 'n_words': 1438}