https://github.com/anatoly-scherbakov/documented
Templated docstrings for Python classes
https://github.com/anatoly-scherbakov/documented
dataclasses docstring-documentation docstrings error-handling exception-handling exceptions python python-library
Last synced: about 1 year ago
JSON representation
Templated docstrings for Python classes
- Host: GitHub
- URL: https://github.com/anatoly-scherbakov/documented
- Owner: anatoly-scherbakov
- License: mit
- Created: 2020-09-28T14:17:57.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2024-02-05T19:30:03.000Z (over 2 years ago)
- Last Synced: 2024-04-25T04:02:44.488Z (about 2 years ago)
- Topics: dataclasses, docstring-documentation, docstrings, error-handling, exception-handling, exceptions, python, python-library
- Language: Python
- Homepage: https://anatoly-scherbakov.github.io/documented/
- Size: 986 KB
- Stars: 13
- Watchers: 1
- Forks: 0
- Open Issues: 9
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Roadmap: docs/roadmap.yaml
Awesome Lists containing this project
README
# documented
[](https://pypi.org/project/documented/)
[](https://github.com/wemake-services/wemake-python-styleguide)
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
```bash
pip install documented
```
## Example
```python
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)
in
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! 🎓
```
For more examples, see: https://anatoly-scherbakov.github.io/documented/
This project was generated with [`wemake-python-package`](https://github.com/wemake-services/wemake-python-package).