{"id":21598952,"url":"https://github.com/eprbell/prezzemolo","last_synced_at":"2025-03-18T11:40:53.058Z","repository":{"id":57165186,"uuid":"527021758","full_name":"eprbell/prezzemolo","owner":"eprbell","description":"Prezzemolo is a collection of classic data structure and algorithms that are useful in many different projects. The goal is to provide components that are robust, efficient and small.","archived":false,"fork":false,"pushed_at":"2023-04-08T16:32:28.000Z","size":72,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-01-24T17:46:36.100Z","etag":null,"topics":["algorithms","avl","classic","computer-science","data-structures","dijkstra","graph","tree"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/eprbell.png","metadata":{"files":{"readme":"README.dev.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2022-08-20T19:32:37.000Z","updated_at":"2023-11-05T06:31:02.000Z","dependencies_parsed_at":"2022-09-13T19:11:25.409Z","dependency_job_id":"4516ef2b-a733-4aa8-9229-43421b947535","html_url":"https://github.com/eprbell/prezzemolo","commit_stats":{"total_commits":32,"total_committers":2,"mean_commits":16.0,"dds":0.25,"last_synced_commit":"1994acc5af751bfdeba28805b64c1fa236a21bed"},"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eprbell%2Fprezzemolo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eprbell%2Fprezzemolo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eprbell%2Fprezzemolo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eprbell%2Fprezzemolo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/eprbell","download_url":"https://codeload.github.com/eprbell/prezzemolo/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244216314,"owners_count":20417596,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["algorithms","avl","classic","computer-science","data-structures","dijkstra","graph","tree"],"created_at":"2024-11-24T18:13:38.532Z","updated_at":"2025-03-18T11:40:53.033Z","avatar_url":"https://github.com/eprbell.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!--- Copyright 2022 eprbell ---\u003e\n\n\u003c!--- Licensed under the Apache License, Version 2.0 (the \"License\"); ---\u003e\n\u003c!--- you may not use this file except in compliance with the License. ---\u003e\n\u003c!--- You may obtain a copy of the License at ---\u003e\n\n\u003c!---     http://www.apache.org/licenses/LICENSE-2.0 ---\u003e\n\n\u003c!--- Unless required by applicable law or agreed to in writing, software ---\u003e\n\u003c!--- distributed under the License is distributed on an \"AS IS\" BASIS, ---\u003e\n\u003c!--- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. ---\u003e\n\u003c!--- See the License for the specific language governing permissions and ---\u003e\n\u003c!--- limitations under the License. ---\u003e\n\n# Prezzemolo v0.0.4 Developer Guide\n[![Static Analysis / Main Branch](https://github.com/eprbell/prezzemolo/actions/workflows/static_analysis.yml/badge.svg)](https://github.com/eprbell/prezzemolo/actions/workflows/static_analysis.yml)\n[![Documentation Check / Main Branch](https://github.com/eprbell/prezzemolo/actions/workflows/documentation_check.yml/badge.svg)](https://github.com/eprbell/prezzemolo/actions/workflows/documentation_check.yml)\n[![Unix Unit Tests / Main Branch](https://github.com/eprbell/prezzemolo/actions/workflows/unix_unit_tests.yml/badge.svg)](https://github.com/eprbell/prezzemolo/actions/workflows/unix_unit_tests.yml)\n[![Windows Unit Tests / Main Branch](https://github.com/eprbell/prezzemolo/actions/workflows/windows_unit_tests.yml/badge.svg)](https://github.com/eprbell/prezzemolo/actions/workflows/windows_unit_tests.yml)\n[![CodeQL/Main Branch](https://github.com/eprbell/prezzemolo/actions/workflows/codeql-analysis.yml/badge.svg)](https://github.com/eprbell/prezzemolo/actions/workflows/codeql-analysis.yml)\n\n## Table of Contents\n* **[Introduction](#introduction)**\n* **[License](#license)**\n* **[Download](#download)**\n* **[Setup](#setup)**\n  * [Ubuntu Linux](#setup-on-ubuntu-linux)\n  * [macOS](#setup-on-macos)\n  * [Windows 10](#setup-on-windows-10)\n  * [Other Unix-like Systems](#setup-on-other-unix-like-systems)\n* **[Source Code](#source-code)**\n* **[Development](#development)**\n  * [Design Guidelines](#design-guidelines)\n  * [Development Workflow](#development-workflow)\n  * [Unit Tests](#unit-tests)\n* **[Creating a Release](#creating-a-release)**\n* **[Localization](#localization)**\n* **[Frequently Asked Developer Questions](#frequently-asked-developer-questions)**\n\n## Introduction\nThis document describes [Prezzemolo](https://github.com/eprbell/prezzemolo) setup instructions, development workflow, design principles and source tree structure.\n\n## License\nPrezzemolo is released under the terms of Apache License Version 2.0. For more information see [LICENSE](LICENSE) or \u003chttp://www.apache.org/licenses/LICENSE-2.0\u003e.\n\n## Download\nThe latest Prezzemolo source can be downloaded at: \u003chttps://github.com/eprbell/prezzemolo\u003e\n\n## Setup\nPrezzemolo has been tested on Ubuntu Linux, macOS and Windows 10 but it should work on all systems that have Python version 3.7.0 or greater. Virtualenv is recommended for Prezzemolo development.\n\n### Setup on Ubuntu Linux\nFirst make sure Python, pip and virtualenv are installed. If not, open a terminal window and enter the following commands:\n```\nsudo apt-get update\nsudo apt-get install python3 python3-pip virtualenv\n```\n\nThen install Prezzemolo Python package requirements:\n```\ncd \u003cprezzemolo_directory\u003e\nvirtualenv -p python3 .venv\n. .venv/bin/activate\n.venv/bin/pip3 install -e '.[dev]'\n```\n### Setup on macOS\nFirst make sure [Homebrew](https://brew.sh) is installed, then open a terminal window and enter the following commands:\n```\nbrew update\nbrew install python3 virtualenv\n```\n\nThen install Prezzemolo Python package requirements:\n```\ncd \u003cprezzemolo_directory\u003e\nvirtualenv -p python3 .venv\n. .venv/bin/activate\n.venv/bin/pip3 install -e '.[dev]'\n```\n### Setup on Windows 10\nFirst make sure [Python](https://python.org) 3.7 or greater is installed (in the Python installer window be sure to click on \"Add Python to PATH\"), then open a PowerShell window and enter the following commands:\n```\npython -m pip install virtualenv\n```\n\nThen install Prezzemolo Python package requirements:\n```\ncd \u003cprezzemolo_directory\u003e\nvirtualenv -p python .venv\n.venv\\Scripts\\activate.ps1\npython -m pip install -e \".[dev]\"\n```\n### Setup on Other Unix-like Systems\n* install python 3.7 or greater\n* install pip3\n* install virtualenv\n* cd _\u003cprezzemolo_directory\u003e_\n* `virtualenv -p python3 .venv`\n* `.venv/bin/pip3 install -e '.[dev]'`\n\n## Source Code\nThe Prezzemolo source tree is organized as follows:\n* `.bumpversion.cfg`: bumpversion configuration;\n* `CHANGELOG.md`: change log document;\n* `CONTRIBUTING.md`: contribution guidelines;\n* `docs/`: additional documentation, referenced from the README files;\n* `.editorconfig`;\n* `.gitattributes`;\n* `.github/workflows/`: configuration of Github continuous integration;\n* `.gitignore`;\n* `.isort.cfg`: isort configuration;\n* `LICENSE`: license information;\n* `Makefile`: alternative old-school build flow;\n* `MANIFEST.in`: source distribution configuration;\n* `mypy.ini`: mypy configuration;\n* `.pre-commit-config.yaml`: pre-commit configuration;\n* `.pylintrc`: pylint configuration;\n* `pyproject.toml`: packaging configuration;\n* `README.dev.md`: developer documentation;\n* `README.md`: user documentation;\n* `setup.cfg`: static packaging configuration file;\n* `setup.py`: dynamic packaging configuration file;\n* `src/prezzemolo`: Prezzemolo code, including classes for transactions, gains, tax engine, balances, logger, ODS parser, etc.;\n* `tests/`: unit tests.\n\n## Development\nRead the [Contributing](CONTRIBUTING.md) document on pull requests guidelines.\n\n### Design Guidelines\nPrezzemolo code adheres to these principles:\n* all identifiers have [descriptive names](https://realpython.com/python-pep8/#how-to-choose-names);\n* immutability:\n  * global variables have upper case names, are initialized where declared and are never modified afterwards;\n  * generally data structures are read-only (the only exceptions are for data structures that would incur a major complexity increase without write permission: e.g. AVL tree node):\n    * class fields are private (prepended with double-underscore). Fields that need public access have a read-only property. Write-properties are not used;\n    * @dataclass classes have `frozen=True`;\n* runtime checks: parameters of public functions are type-checked at runtime;\n* type hints: all variables and functions have Python type hints (with the exception of local variables, for which type hints are optional);\n* no id-based hashing: classes that are added to dictionaries and sets redefine `__eq__()`, `__neq__()` and `__hash__()`;\n* f-strings only: every time string interpolation is needed, f-strings are used;\n* no raw strings (unless they occur only once): use global constants instead;\n* no unnamed tuples: dataclasses or named tuples are used instead;\n* one class per file (with exceptions for trivial classes);\n* files containing a class must have the same name as the class (but lowercase with underscores): e.g. class AbstractEntry lives in file abstract_entry.py;\n* abstract class names start with `Abstract`;\n* no imports with `*`.\n\n### Development Workflow\nPrezzemolo uses pre-commit hooks for quick validation at commit time and continuous integration via Github actions for deeper testing. Pre-commit hooks invoke: flake8, black, isort, pyupgrade and more. Github actions invoke: mypy, pylint, bandit, unit tests (on Linux, Mac and Windows), markdown link check and more.\n\nWhile every commit and push is automatically tested as described, sometimes it's useful to run some of the above commands locally without waiting for continuous integration. Here's how to run the most common ones:\n* run unit tests: `pytest --tb=native --verbose`\n* type check: `mypy src tests`\n* lint: `pylint -r y src tests/*.py`\n* security check: `bandit -r src`\n* reformat code: `black src tests`\n* sort imports: `isort .`\n* run pre-commit tests without committing: `pre-commit run --all-files`\n\n### Unit Tests\nPrezzemolo has unit test coverage to reduce the risk of regression. Unit tests are in the [tests](tests) directory. Please add unit tests for any new code.\n\n## Creating a Release\nThis section is for project maintainers.\n\nTo create a new release:\n* add a section named as the new version in CHANGELOG.md\n* use the output of `git log` to collect significant changes since last version and add them to CHANGELOG.md as a list of brief bullet points\n* `git add CHANGELOG.md`\n* `git commit -m \"Updated with latest changes\" CHANGELOG.md`\n* `bumpversion patch` (or `bumpversion minor` or `bumpversion major`)\n* `git push`\n* wait for all tests to pass successfully on Github\n* add a tag in Github (named the same as the version but with a `v` in front, e.g. `v1.0.4`):  click on \"Releases\" and then \"Draft a new release\"\n\nTo create a Pypi distribution:\n* `make distribution`\n* `make upload_distribution`\n\n## Frequently Asked Developer Questions\nRead the [frequently asked developer questions](docs/developer_faq.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feprbell%2Fprezzemolo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feprbell%2Fprezzemolo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feprbell%2Fprezzemolo/lists"}