<commit_before>===========
rectype API
===========
*wrecord* is a Python module for creating lightweight record types with mutable
field values. Rectype fields are accessible using named attributes
as well as being indexable and iterable.

--------------------------------------------------------------------------------
:py:func:`wrecord` factory function for record classes with mutable field values
--------------------------------------------------------------------------------

.. py:function:: wrecord(typename, fieldnames, rename=False)

    Create a new record class with fields accessible by named attributes.

    The new type is a subclass of ``collections.Sequence`` named *typename*.

    The new subclass is used to create ``wrecord`` objects that have
    fields accessible by attribute lookup as well as being indexable
    and iterable. Per-field default values can be set. These are assigned
    to fields that are not supplied a value when new instances of the
    subclass are initialised.

    Basic example::

        >>> Point = wrecord('Point', 'x y')  # create a new record type
        >>> p = Point(x=1, y=2)              # instantiate with keyword arguments
        >>> p[0]                             # indexable like lists
        1
        >>> p.y                              # fields also accessible by name
        2
        >>> p                                # readable __repr__ with name=value style
        Point(x=1, y=None)
        >>> # Create a new record type with default field values
        >>> Point = wrecord('Point', [('x', None), ('y', None)])
        >>> p = Point(x=1)                   # fields with defaults do not need to be specified
        >>> p                                # y has been assigned a default value
        Point(x=1, y=None)

    :param typename: Name of the subclass to create, e.g. ``'MyRecord'``.
    :param fieldnames: Specifies the fieldnames and optional per-field
        default values of the record. It cam be a single string with each
        fieldname separated by whitespace and/or commas such as ``'x, y'``;
        a sequence of strings such as ``['x', 'y']`` and/or 2-tuples of the
        form ``(fieldname, default_value)`` such as ``[('x', None), ('y', None)]
        ``; a mapping of fieldname-default_value pairs such as
        ``collections.OrderedDict([('x', None), ('y', None)])``.

        Note, it only makes sense to use an ordered mapping (e.g.
        ``OrderedDict``) since access by index or iteration is affected by the
        order of the fieldnames.

        A fieldname may be any valid Python identifier except for names
        starting with an underscore.
    :param rename: If set to ``True``, invalid fieldnames are automatically
        replaced with positional names. For example,
        ('abc', 'def', 'ghi', 'abc') is converted to
        ('abc', '_1', 'ghi', '_3'), eliminating the keyword 'def' and the
        duplicate fieldname 'abc'.
    :returns: A subclass of ``collections.Sequence`` named *typename*.
    :raises: ValueError if *typename* is invalid or *fieldnames*
        contains an invalid fieldname and rename is ``False``.

Instances of classes created by ``wrecord.wrecord()`` are created as follows:

.. py:class:: SomeRecType(*values_by_field_order, **values_by_fieldname)

    Return a new wrecord object.

    Field values can be passed by field order, fieldname, or both.

    The following examples all return a wrecord equivalent to
    ``Rec(a=1, b=2, c=3)``::

        >>> Rec = wrecord('Rec', 'a b c')
        >>> rec = Rec(1, 2, 3)                # using positional args
        >>> rec = Rec(a=1, b=2, c=3)          # using keyword args
        >>> rec = Rec(*[1, 2, 3])             # using a sequence
        >>> rec = Rec(**dict(a=1, b=2, c=3))  # using a mapping
        >>> rec = Rec(*[1, 2], c=3)           # using an unpacked sequence and keyword arg
        >>> rec
        Rec(a=1, b=2, c=3)

    Since wrecord instances are iterable they can be used to initialise
    other instances of the same type by unpacking them::

        >>> rec2 = Rec(*rec)
        >>> rec2 == rec
        True

    If a field has not been supplied a value by an argument, its default value
    will be used (if one has been defined).

    :param *values_by_field_order: Field values passed by field order.
    :param **values_by_fieldname: Field values passed by fieldname.
    :raises: ``TypeError`` if the number of positional arguments exceeds the
         number of fields, a keyword argument does not match a fieldname,
         or a keyword argument redefines a positional argument.
         ``ValueError`` if a field has not been defined by the positional
         or keyword arguments and has no default value set.

Methods and attributes
----------------------
These are the methods and attributes supported by wrecords. To prevent
conflicts with fieldnames, the method and attribute names start with an
underscore.

.. py:attribute:: somerecord._fieldnames

    Tuple of strings listing the fieldnames. Useful for introspection and
    creating new record types from existing record types. Should not be
    changed.

    Example usage::

        >>> Point = wrecord('Point', 'x y')  # create a new record type
        >>> Point._fieldnames       # view the fieldnames
        ('x', 'y')
        >>> Point3D = wrecord('Point3D', Point._fieldnames + ('z',))
        >>> Point3D._fieldnames
        ('x', 'y', 'z')

.. py:classmethod:: _get_defaults()

    Return a dict that maps fieldnames to their corresponding default_value.
    If no default values are set an empty dict is returned.

.. py:classmethod:: somerecord._replace_defaults(*values_by_field_order, **values_by_fieldname)

    Replace the existing per-field default values.<commit_msg>Tweaked some formatting and text<commit_after>===
API
===
*wrecord* is a Python module for creating lightweight record types with mutable
field values and per-field defaults. Fields are accessible using named
attributes as well as being indexable and iterable.

-------------------------------------------------------
:py:func:`wrecord` factory function for *wrecord* types
-------------------------------------------------------

.. py:function:: wrecord(typename, fieldnames, rename=False)

    Create a new record class with fields accessible by named attributes.

    The new type is a subclass of ``collections.Sequence`` named *typename*.

    The new subclass is used to create record objects that have fields
    accessible by attribute lookup as well as being indexable and
    iterable. Per-field default values can be set. These are assigned
    to fields that are not supplied a value when new instances of the
    subclass are initialised.

    Basic example::

        >>> Point = wrecord('Point', 'x y')  # create a new record type
        >>> p = Point(x=1, y=2)              # instantiate with keyword arguments
        >>> p[0]                             # indexable like lists
        1
        >>> p.y                              # fields also accessible by name
        2
        >>> p                                # readable __repr__ with name=value style
        Point(x=1, y=None)
        >>> # Create a new record type with default field values
        >>> Point = wrecord('Point', [('x', None), ('y', None)])
        >>> p = Point(x=1)                   # fields with defaults do not need to be specified
        >>> p                                # y has been assigned a default value
        Point(x=1, y=None)

    :param typename: Name of the subclass to create, e.g. ``'MyRecord'``.
    :param fieldnames: Specifies the fieldnames and optional per-field
        default values of the record. It cam be a single string with each
        fieldname separated by whitespace and/or commas such as ``'x, y'``;
        a sequence of strings such as ``['x', 'y']`` and/or 2-tuples of the
        form ``(fieldname, default_value)`` such as
        ``[('x', None), ('y', None)]``; a mapping of fieldname-default_value
        pairs such as ``collections.OrderedDict([('x', None), ('y', None)])``.

        Note, it only makes sense to use an ordered mapping (e.g.
        ``OrderedDict``) since access by index or iteration is affected by the
        order of the fieldnames.

        A fieldname may be any valid Python identifier except for names
        starting with an underscore.
    :param rename: If set to ``True``, invalid fieldnames are automatically
        replaced with positional names. For example,
        ('abc', 'def', 'ghi', 'abc') is converted to
        ('abc', '_1', 'ghi', '_3'), eliminating the keyword 'def' and the
        duplicate fieldname 'abc'.
    :returns: A subclass of ``collections.Sequence`` named *typename*.
    :raises: ValueError if *typename* is invalid or *fieldnames*
        contains an invalid fieldname and rename is ``False``.

Instances of classes created by ``wrecord.wrecord()`` are created as follows:

.. py:class:: SomeWrecordType(*values_by_field_order, **values_by_fieldname)

    Return a new wrecord object.

    Field values can be passed by field order, fieldname, or both.

    The following examples all return a wrecord equivalent to
    ``Rec(a=1, b=2, c=3)``::

        >>> Rec = wrecord('Rec', 'a b c')
        >>> rec = Rec(1, 2, 3)                # using positional args
        >>> rec = Rec(a=1, b=2, c=3)          # using keyword args
        >>> rec = Rec(*[1, 2, 3])             # using a sequence
        >>> rec = Rec(**dict(a=1, b=2, c=3))  # using a mapping
        >>> rec = Rec(*[1, 2], c=3)           # using an unpacked sequence and keyword arg
        >>> rec
        Rec(a=1, b=2, c=3)

    Since wrecord instances are iterable they can be used to initialise
    other instances of the same type by unpacking them::

        >>> rec2 = Rec(*rec)
        >>> rec2 == rec
        True

    If a field has not been supplied a value by an argument, its default value
    will be used (if one has been defined).

    :param *values_by_field_order: Field values passed by field order.
    :param **values_by_fieldname: Field values passed by fieldname.
    :raises: ``TypeError`` if the number of positional arguments exceeds the
         number of fields, a keyword argument does not match a fieldname,
         or a keyword argument redefines a positional argument.
         ``ValueError`` if a field has not been defined by the positional
         or keyword arguments and has no default value set.

Methods and attributes
----------------------
These are the methods and attributes supported by wrecord types. To prevent
conflicts with fieldnames, the method and attribute names start with an
underscore.

.. py:attribute:: somerecord._fieldnames

    Tuple of strings listing the fieldnames. Useful for introspection and
    creating new record types from existing record types. Should not be
    changed.

    Example usage::

        >>> Point = wrecord('Point', 'x y')  # create a new record type
        >>> Point._fieldnames       # view the fieldnames
        ('x', 'y')
        >>> Point3D = wrecord('Point3D', Point._fieldnames + ('z',))
        >>> Point3D._fieldnames
        ('x', 'y', 'z')

.. py:classmethod:: _get_defaults()

    Return a dict that maps fieldnames to their corresponding default_value.
    If no default values are set an empty dict is returned.

.. py:classmethod:: somerecord._replace_defaults(*values_by_field_order, **values_by_fieldname)

    Replace the existing per-field default values.
{'fraction_non_alphanumeric': 0.12250736951621294, 'fraction_numerical': 0.006415814114791052, 'mean_word_length': 2.367883211678832, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 135, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 14, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1397523', 'n_tokens_mistral': 3056, 'n_tokens_neox': 2946, 'n_words': 1339}