# -*- coding: utf-8 -*-
from setuptools import setup

packages = \
['pydoctrace', 'pydoctrace.domain', 'pydoctrace.exporters']

package_data = \
{'': ['*']}

setup_kwargs = {
    'name': 'pydoctrace',
    'version': '0.1.0',
    'description': 'Generate sequence diagrams by tracing Python code execution',
    'long_description': '# pydoctrace\n\nGenerate sequence diagrams by tracing Python code execution.\n\nHere are the sequence diagrams produced by 2 different implementations of the `factorial` function (*n * n-1 * n-2 * ... * 1*).\nOne which loops, another one that is recursive:\n\n<table>\n<tbody>\n<tr>\n<td valign="bottom">\n\n```python\nfrom pydoctrace.doctrace import trace_to_puml\n\n@trace_to_puml\ndef factorial_reduce_multiply(value: int) -> int:\n    if value <= 1:\n        return value\n\n    def multiply(agg: int, value: int) -> int:\n        return agg * value\n\n    return reduce(multiply, range(1, value + 1), 1)\n```\n\n</td>\n<td valign="bottom">\n\n```python\nfrom pydoctrace.doctrace import trace_to_puml\n\n@trace_to_puml\ndef factorial_recursive(value: int) -> int:\n    if value <= 1:\n        return value\n\n    return value * factorial_recursive(value - 1)\n```\n\n</td>\n</tr>\n<tr>\n<td valign="top"><pre>tests.modules.factorial.factorial_reduce_multiply.puml</pre>\n<img src="https://www.plantuml.com/plantuml/svg/rP0nYof148Jp_XMDgUYweZwHnqCqUDaXNEY1Z3kzEZZRlVJsW88__WAvKmurCBhDXgcYwgkUD-RKKXNHgB6cNubFaPf-wGeJ3IvUNnibdmhQL2bQgEC9caFWsgchS277bVC-y0xpmSt_ogc58jIExKiVtyXlOhHmnM6dajWl9OhYKfIR40y_RQAUz69v3yJiO1yyOIbYMpa2hANt3piFHdpmmnKTO3523RkzpJ069Xpb0AyauLE2gwtRlNH6AhyhftSmnW1AbfGnlwDEu7m-_pRGOLj09wsvwAWjfFbmq1RKFyzGrtzxFNo5T_OWTmfGYXWf_YScTKOUjoVCilhafJ1r1MKPp8bzgY9y0W00" /></td>\n<td valign="top"><pre>tests.modules.factorial.factorial_recursive.puml</pre>\n<img src="https://www.plantuml.com/plantuml/svg/xP31QYf144Nt_HM5Mz5nv3qJ90JHHNP1oD90AAThjB6dIgghWu8Vdu2OI8o8PEkkwNkuzr2ZPAYMcmX6oLAt4PyZfMwDbOa6ZD-lDwKgQmhlvD8gy1eL6nZBPehU1rv0sJlwdw9QgC8QsGxv_wFuMOp6MAqMAfdzHA8eJ4GvXRZwYObwqZto4eWPtJ9uWbh4vh9nRYQTHsYTqN_bN_nRZiK8D2oMDeGOc63Wt7KLSFKejDlxtKZrORRitLHkAdzIKRAi3ELfUEzskzqNq3y5FXkFYS55el_l8bBsU-UPsKEdS-KbXd1tfj7L8aOAJyIaQEHXleMYM6-zLAPOKL6u4R7FJNGV" /></td>\n</tr>\n</tbody>\n</table>\n\n## Installation\n\nUse your favorite dependency manager to install `pydoctrace`:\n\n```sh\n# using pip\npip install pydoctrace\n\n# using poetry\npoetry add pydoctrace\n\n# using pipenv\npipenv install pydoctrace\n```\n\n## Purposes and mechanisms\n\nThe purpose of `pydoctrace` is to document the execution of some code to illustrate the behavior and the structure of the code base.\n\n- the documentation produced is a sequence diagram;\nwhich lets you see how the functions are called, how the values are returned and how the errors are handled\n- with one of the provided decorators (depending on the export format you want), decorate the function whose execution you want to document\n- run your code, when the execution hits the decorated function, the execution is traced and the sequence diagram will be drawn in the format of your choice\n\n`pydoctrace` is a pure Python tool relying on no other 3rd-party library to work.\nThe project involves development libraries for testing and documentation purposes.\n\n### Doc-tracing\n\nThis approach, which I called "doc-tracing" (tracing code execution for documentation purposes), is meant to be complementary of other approaches which generate documentation from static code analysis.\nStatic code analysis reads the source code to detect and document data structures (classes, dataclasses, named tuples, enumeration, etc.), functions names and signatures (parameters name and types, returned value types).\n\nUseful as it is, static code analysis does not help much to understand how the code pieces work together; doc-tracing attempts to complement this approach by producing documentation while the code runs.\nSome use cases:\n\n- you start working on a legacy codebase: study the behavior of a particular function by temporarily tracing its executions\n- you finished a user story, document its implementation by tracing the execution of some **integration tests** (*"given ... when ... then ..."*) to illustrate how right cases and errors are handled.\n- generally, the sequence diagrams illustrate how the modules and functions interacts; and as such, **they help discussing architecture**\n- tracing code execution can also be useful when teaching computer programming to illustrate how algorithms work\n\n\n### How is the code execution traced?\n\nWhen a function decorated by `pydoctrace` is called:\n\n1. a context manager is created\n2. during which a **tracing function** is passed to [sys.settrace](https://docs.python.org/3/library/sys.html#sys.settrace), which is called when different events happens in the execution stack:\n    - when functions are called\n    - when values are returned\n    - when exceptions are raised or handled\n3. the sequence diagram is drawn and exported in a file alongside the code execution so that its memory footprint is minimal\n4. once the decorated function stops its execution, the tracing function is removed from the code execution\n\n⚠️ **Caveat**: `pydoctrace` uses the `sys.settrace` API, which is meant to be used by debuggers.\nTherefore, a warning is emitted when `pydoctrace` is used in a debug mode (and does not trace the decorated function anymore).\n\n# Tests\n\n```sh\n# directly with poetry\npoetry run pytest -v\n\n# in an activated virtual environment\npytest -v\n```\n\nCode coverage (with [missed branch statements](https://pytest-cov.readthedocs.io/en/latest/config.html?highlight=--cov-branch)):\n\n```sh\npoetry run pytest -v --cov=pydoctrace --cov-branch --cov-report term-missing --cov-fail-under 50\n```\n\n# Changelog\n\n* `0.1.0`: ✨ first release, PlantUML exporter; diagram files are saved in the current working directory\n\n# Licence\n\nUnless stated otherwise all works are licensed under the [MIT license](http://spdx.org/licenses/MIT.html), a copy of which is included [here](LICENSE).\n\n# Contributions\n\n* [Luc Sorel-Giffo](https://github.com/lucsorel)\n\n## Pull requests\n\nPull-requests are welcome and will be processed on a best-effort basis.\n\nPull requests must follow the guidelines enforced by the `pre-commit` hooks:\n\n- commit messages must follow the Angular conventions enforced by the `commitlint` hook\n- code formatting must follow the conventions enforced by the `isort` and `yapf` hooks\n- code linting should not detect code smells in your contributions, this is checked by the `ruff` hook\n\n## Code conventions\n\nThe code conventions are described and enforced by [pre-commit hooks](https://pre-commit.com/hooks.html) to maintain consistency across the code base.\nThe hooks are declared in the [.pre-commit-config.yaml](.pre-commit-config.yaml) file.\n\nSet the git hooks (pre-commit and commit-msg types):\n\n```sh\npoetry run pre-commit install --hook-type pre-commit --hook-type commit-msg\n```\n\nBefore committing, you can check your changes with:\n\n```sh\n# put all your changes in the git staging area\ngit add -A\n\n# all hooks\npoetry run pre-commit run --all-files\n\n# a specific hook\npoetry run pre-commit run ruff --all-files\n```\n\n### Commit messages\n\nPlease, follow the [conventions of the Angular team](https://github.com/angular/angular/blob/main/CONTRIBUTING.md#-commit-message-format) for commit messages.\nWhen merging your pull-request, the new version of the project will be derived from the messages.\n\n### Code formatting\n\nThis project uses `isort` and `yapf` to format the code.\nThe guidelines are expressed in their respective sections in the [pyproject.toml](pyproject.toml) file.\n\n### Best practices\n\nThis project uses the `ruff` linter, which is configured in its section in the [pyproject.toml](pyproject.toml) file.\n\n# Similar tools and bibliography\n\n- https://stackoverflow.com/questions/45238329/it-is-possible-to-generate-sequence-diagram-from-python-code\n- https://github.com/gaogaotiantian/viztracer\n- https://9to5answer.com/how-to-generate-a-sequence-diagram-from-java-source-code\n- https://medium.com/javarevisited/how-to-generate-sequence-diagrams-in-intellij-e2bb7cec2b0b\n',
    'author': 'Luc Sorel-Giffo',
    'author_email': 'None',
    'maintainer': 'Luc Sorel-Giffo',
    'maintainer_email': 'None',
    'url': 'https://github.com/lucsorel/pydoctrace',
    'packages': packages,
    'package_data': package_data,
    'python_requires': '>=3.8,<4.0',
}


setup(**setup_kwargs)
