Metadata-Version: 2.1
Name: reprfunc
Version: 0.0.0
Summary: Utilities for making useful string representations of objects.
Author-email: Kale Kundert <kale@thekunderts.net>
Requires-Python: ~=3.7
Description-Content-Type: text/x-rst
Classifier: Programming Language :: Python :: 3.7
Requires-Dist: sphinx ; extra == "doc"
Requires-Dist: sphinx_rtd_theme ; extra == "doc"
Requires-Dist: autoclasstoc ; extra == "doc"
Requires-Dist: pytest ; extra == "test"
Requires-Dist: pytest-cov ; extra == "test"
Requires-Dist: parametrize_from_file ; extra == "test"
Requires-Dist: coveralls ; extra == "test"
Project-URL: Bug Tracker, https://github.com/kalekundert/reprfunc/issues
Project-URL: Continuous Integration, https://github.com/kalekundert/reprfunc/actions
Project-URL: Documentation, https://reprfunc.readthedocs.io/en/latest/
Project-URL: Test Coverage, https://coveralls.io/github/kalekundert/reprfunc
Project-URL: Version Control, https://github.com/kalekundert/reprfunc
Provides-Extra: doc
Provides-Extra: test

********
reprfunc
********

.. image:: https://img.shields.io/pypi/v/reprfunc.svg
   :alt: Last release
   :target: https://pypi.python.org/pypi/reprfunc

.. image:: https://img.shields.io/pypi/pyversions/reprfunc.svg
   :alt: Python version
   :target: https://pypi.python.org/pypi/reprfunc

.. image:: https://img.shields.io/readthedocs/reprfunc.svg
   :alt: Documentation
   :target: https://reprfunc.readthedocs.io/en/latest/?badge=latest

.. image:: https://img.shields.io/github/workflow/status/kalekundert/reprfunc/Test%20and%20release/master
   :alt: Test status
   :target: https://github.com/kalekundert/reprfunc/actions

.. image:: https://img.shields.io/coveralls/kalekundert/reprfunc.svg
   :alt: Test coverage
   :target: https://coveralls.io/github/kalekundert/reprfunc?branch=master

.. image:: https://img.shields.io/github/last-commit/kalekundert/reprfunc?logo=github
   :alt: Last commit
   :target: https://github.com/kalekundert/reprfunc

``reprfunc`` is a library that makes it easier to implement ``__repr__()`` for 
your classes.  It implements a few common repr strategies (e.g. mimicking the 
contructor, getting values from a custom dunder method, displaying a hard-coded 
list of object attributes) and allows you use them simply by assigning to 
``__repr__``.

Installation
============

Install ``reprfunc`` from PyPI::

  $ pip install reprfunc

Version numbers obey semantic versioning.

Examples
========
Make a repr-string that matches the arguments to the constructor::

  >>> from reprfunc import *
  >>> class MyObj:
  ...
  ...     def __init__(self, a, b):
  ...         self.a = a
  ...         self.b = b
  ...
  ...     __repr__ = repr_from_init
  ...
  >>> MyObj(1, 2)
  MyObj(a=1, b=2)

The same as above, but also demonstrating some knobs for controlling the 
output::

  >>> class MyObj:
  ...
  ...     def __init__(self, a, b, c=None, _state={}):
  ...         self.a = a
  ...         self._b = b
  ...         self.c = c
  ...         self._state = _state
  ...
  ...     __repr__ = repr_from_init(
  ...         # This option lets you explicitly map argument names to either
  ...         # attribute names, or callables that accept the object in
  ...         # question as their only argument.
  ...         attrs={'b': '_b'},
  ...
  ...         # This option allows you to exclude certain arguments from the
  ...         # repr-string.  Attributes with the same value as the default # 
  ...         # will be skipped automatically (like `c` in this example).
  ...         skip=['_state'],
  ...
  ...         # This option allows you to specify that certain arguments should 
  ...         # be rendered using the "positional" syntax.  Positional-only
  ...         # arguments are rendered this way by default.
  ...         positional=['a'],
  ...     )
  >>> MyObj(1, 2, _state={3: 4})
  MyObj(1, b=2)

Make a repr-string that gets its values from a `__reprargs__()` method defined 
by the object in question::

  >>> class MyObj:
  ...
  ...     def __init__(self, a, b):
  ...         self.a = a
  ...         self.b = b
  ...
  ...     def __reprargs__(self):
  ...         # This function should return a list and a dictionary.  Any
  ...         # values in the list will be rendered as positional arugments,
  ...         # and any items in the dictionary will be rendered as keyword
  ...         # arguments.
  ...         return [self.a], {'b': self.b}
  ...
  ...     __repr__ = repr_from_dunder
  ...
  >>> MyObj(1, 2)
  MyObj(1, b=2)

Make a repr-string from a hard-coded list of attributes::

  >>> class MyObj:
  ...
  ...     def __init__(self, a, b):
  ...         self.a = a
  ...         self.b = b
  ...
  ...     # Note that 'b' is specified twice here.  You can avoid this by
  ...     # specifying ``b=Key()``.
  ...     __repr__ = repr_from_attrs('a', b='b')
  ...
  >>> MyObj(1, 2)
  MyObj(1, b=2)

Use `ReprBuilder` to help formatting bespoke repr-strings.  You can think of 
this class as a collection of positional and keyword arguments that knows how 
to format itself.  It provides many more methods for registering 
positional/keyword arguments beyond what's demonstrated here, so consult the 
source code if this seems useful::

  >>> class MyObj:
  ...
  ...    def __init__(self, a, b):
  ...        self.a = a
  ...        self.b = b
  ...
  ...    def __repr__(self):
  ...        builder = ReprBuilder(self)
  ...        builder.add_positional_attr('a')
  ...        builder.add_keyword_attr('b')
  ...        return str(builder)
  ...
  >>> MyObj(1, 2)
  MyObj(1, b=2)

Alternatives
============
There are several other libraries out there that help with formatting 
repr-strings.  Overall, the reason I wrote ``reprfunc`` was to make something 
more flexible and more succinct than the alternatives.

- ``represent``: This is a pretty similar library overall.  The main difference 
  is that it uses class decorators and/or inheritance to add its repr functions 
  to your objects.  One big advantage of this approach is that it allows 
  "pretty-print" reprs for IPython to be added at the same time, but it also 
  has a heavier feel.

- ``reprutils``: This is also a pretty similar library, but it only supports 
  the equivalent of ``repr_from_attrs()``.

- ``reprtools``: This library doesn't have much documentation, but seems to be 
  mostly superseded by f-strings.

