Skip to main content

Templated docstrings for Python classes.

Project description

documented

Build Status Coverage Python Version wemake-python-styleguide PyPI - License

Templated docstrings for Python classes.

Features

  • Describe your business logic in docstrings of your classes and exceptions;
  • When printing an object or an exception, the library will substitute the placeholders in the docstring text with runtime values,
  • And you (or your user) will see a human readable text.

Installation

pip install documented

Example

from dataclasses import dataclass
from documented import DocumentedError


@dataclass
class InsufficientWizardryLevel(DocumentedError):
    """
    🧙 Your level of wizardry is insufficient ☹

        Spell: {self.spell}
        Minimum level required: {self.required_level}
        Actual level: {self.actual_level} {self.comment}

    Unseen University will be happy to assist in your training! 🎓
    """

    spell: str
    required_level: int
    actual_level: int

    @property
    def comment(self) -> str:
        if self.actual_level <= 0:
            return '(You are Rincewind, right? Hi!)'
        else:
            return ''


raise InsufficientWizardryLevel(
    spell='Animal transformation',
    required_level=8,
    actual_level=0,
)

which prints:

---------------------------------------------------------------------
InsufficientWizardryLevel           Traceback (most recent call last)
<ipython-input-1-d8ccdb953cf6> in <module>
     27 
     28 
---> 29 raise InsufficientWizardryLevel(
     30     spell='Animal transformation',
     31     required_level=8,

InsufficientWizardryLevel: 
🧙 Your level of wizardry is insufficient ☹

    Spell: Animal transformation
    Minimum level required: 8
    Actual level: 0 (You are Rincewind, right? Hi!)

Unseen University will be happy to assist in your training! 🎓

Usage

  • Template rendering is done using str.format().
  • That function receives the object instance as self keyword argument.
  • From template, you can't call methods of the object, but you can access its fields and properties.
  • textwrap.dedent() is applied to the result, thus Python indentation rules do not corrupt the resulting message.

Dynamically computed pieces of content may be introduced using:

You can also access elements of lists and dicts by index, for example: {self.countries[US]}.

Making your exceptions sane

  • Create your own exception classes in terms of your domain, to play a part in your business logic.

  • Do not use the word Exception or Error in their names. Your code should raise things like:

    • BalanceInsufficient
    • PlanetNotFound
    • TetOffline
    • OrderDeclined

    And should not:

    • ValueError
    • Exception
    • CatastrophicalError
  • Store meaningful properties of your errors in fields of the exception classes.

  • Use dataclasses, attrs or pydantic to save yourself from boilerplate in __init__() — and to get IDE support.

  • Maintain docstrings of your exceptions to contain up-to-date, human readable descriptions of what they mean.

  • You will be stimulated to do this by documented: when an exception happens, the docstring becomes actually useful.

Links

Which actually explains the meaning of this little helper: if we're stuck with exceptions in Python, why not at least make them friendlier?

This project was generated with wemake-python-package. Current template version is: 5840464a31423422d7523897d854e92408eee6b8. See what is updated since then.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

documented-0.1.2.tar.gz (5.5 kB view hashes)

Uploaded Source

Built Distribution

documented-0.1.2-py3-none-any.whl (5.4 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page