# Sourcery Rules Generator
**This is an experimental project. It might become a part of the [Sourcery CLI](https://docs.sourcery.ai/Overview/Products/Command-Line/).**
Sourcery Rules Generator creates architecture rules for your project.
The generated rules can be used by Sourcery to review your project's architecture.
Currently, the project can create dependency rules.
## Usage
You can create Sourcery rules based on a template with the command:
```
sourcery-rules <TEMPLATE-NAME> create
```
Supported templates:
* [dependencies](#create-dependencies-rules)
* [naming / voldemort](#create-voldemort-rules): avoid some names
* naming / name vs type mismatch (coming soon)
For example:
```
sourcery-rules dependencies create
```
### Create Dependencies Rules
With the dependencies template, you can create rules to check the dependencies:
* between the packages of your application
* to external packages.
Let's say your project has an architecture like this:
You can create rules to ensure:
* no other package imports `api`
* only `api` imports `core`
* only `db` import `SQLAlchemy`
* etc.
Run the command:
```
sourcery-rules dependencies create
```
You'll be prompted to provide:
* a package name
* the packages that are allowed to import the package above
The 1st parameter is the fully qualified name of a package or module.
It can be a package within your project or an external dependency.
The 2nd parameter is optional.
You have the following possibilities:
* 0 allowed importer (e.g. for packages like `api`, `cli`). Leave this parameter empty.
* 1 allowed importer. Provide the importer package's fully qualified name.
* Multiple allowed importers. Provide multiple fully qualified package names separated by a comma `,`
=>
2 rules will be generated:
* 1 for `import` statements
* 1 for `from ... import` statements
Every generated rule allows imports:
* within the package itself
* in tests
## Dependencies Use Cases
### Internal Dependencies Between the Packages of a Project
* [Law of Demeter](https://en.wikipedia.org/wiki/Law_of_Demeter): Packages should talk only to their "direct neighbors".
* A mature package shouldn't depend on a less mature package
* A core package shouldn't depend on a customer-specific package
Thanks to [w_t_payne](https://news.ycombinator.com/user?id=w_t_payne) and [hbrn](https://news.ycombinator.com/user?id=hbrn) for their input in this [HackerNews discussion](https://news.ycombinator.com/item?id=33999191#34001608) 😃
### External Dependencies
* [Gateway pattern](https://martinfowler.com/articles/gateway-pattern.html): Ensure that only a dedicated package of your software communicates with an external dependency.
* Ensure that a deprecated library isn't used
This [blog post](https://sourcery.ai/blog/dependency-rules/) shows a 3-step method of defining dependency rules:
1. Draw a diagram showing the optimal dependencies between your packages.
2. Phrase some rules in a human language based on the diagram: Which package should depend on which?
3. Translate the rules into code with Sourcery Rules Generator.
## Create Voldemort Rules
With a "voldemort" template, you can create rules that ensure that a specific name isn't used in your code.
For example:
* The word `annual` shouldn't be used, because the preferred term is `yearly`.
* The word `util` shouldn't be used, because it's overly general.
You can create a "voldemort" rule with the command:
```
sourcery-rules voldemort create
```
You'll be prompted to provide:
* the name that you want to avoid
=>
5 rules will be generated:
* function names
* function arguments
* class names
* variable declarations
* variable assignments
## Using the Generated Rules
The generated rules can be used by Sourcery to review your project.
If you copy the generated rules into your project's `.sourcery.yaml`, Sourcery will use them automatically.
All the generated rules have the tag `architecture`. Once you've copied them to your `.sourcery.yaml`, you can run them with:
```
sourcery review --enable architecture .
```
Raw data
{
"_id": null,
"home_page": "https://github.com/sourcery-ai/sourcery-rules-generator",
"name": "sourcery-rules-generator",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9,<4.0",
"maintainer_email": "",
"keywords": "architecture,development",
"author": "reka",
"author_email": "reka@sourcery.ai",
"download_url": "https://files.pythonhosted.org/packages/70/9d/13b79471510ecedd9d8304158b79add1c9d3aff82a6605a4ddf6c6a7a9ff/sourcery_rules_generator-0.5.0.tar.gz",
"platform": null,
"description": "# Sourcery Rules Generator \n\n**This is an experimental project. It might become a part of the [Sourcery CLI](https://docs.sourcery.ai/Overview/Products/Command-Line/).**\n\nSourcery Rules Generator creates architecture rules for your project.\n\nThe generated rules can be used by Sourcery to review your project's architecture.\n\nCurrently, the project can create dependency rules.\n\n## Usage\n\nYou can create Sourcery rules based on a template with the command:\n\n```\nsourcery-rules <TEMPLATE-NAME> create\n```\n\nSupported templates:\n\n* [dependencies](#create-dependencies-rules)\n* [naming / voldemort](#create-voldemort-rules): avoid some names\n* naming / name vs type mismatch (coming soon)\n\nFor example:\n\n```\nsourcery-rules dependencies create\n```\n\n\n\n### Create Dependencies Rules\n\nWith the dependencies template, you can create rules to check the dependencies:\n\n* between the packages of your application\n* to external packages.\n\nLet's say your project has an architecture like this:\n\n\n\nYou can create rules to ensure:\n\n* no other package imports `api`\n* only `api` imports `core`\n* only `db` import `SQLAlchemy`\n* etc.\n\nRun the command:\n\n```\nsourcery-rules dependencies create\n```\n\nYou'll be prompted to provide:\n\n* a package name\n* the packages that are allowed to import the package above\n\nThe 1st parameter is the fully qualified name of a package or module. \nIt can be a package within your project or an external dependency.\n\nThe 2nd parameter is optional. \nYou have the following possibilities:\n\n* 0 allowed importer (e.g. for packages like `api`, `cli`). Leave this parameter empty.\n* 1 allowed importer. Provide the importer package's fully qualified name.\n* Multiple allowed importers. Provide multiple fully qualified package names separated by a comma `,`\n\n=>\n\n2 rules will be generated:\n\n* 1 for `import` statements\n* 1 for `from ... import` statements\n\nEvery generated rule allows imports:\n\n* within the package itself\n* in tests\n\n## Dependencies Use Cases\n\n### Internal Dependencies Between the Packages of a Project\n\n* [Law of Demeter](https://en.wikipedia.org/wiki/Law_of_Demeter): Packages should talk only to their \"direct neighbors\".\n* A mature package shouldn't depend on a less mature package\n* A core package shouldn't depend on a customer-specific package\n\nThanks to [w_t_payne](https://news.ycombinator.com/user?id=w_t_payne) and [hbrn](https://news.ycombinator.com/user?id=hbrn) for their input in this [HackerNews discussion](https://news.ycombinator.com/item?id=33999191#34001608) \ud83d\ude03\n\n### External Dependencies\n\n* [Gateway pattern](https://martinfowler.com/articles/gateway-pattern.html): Ensure that only a dedicated package of your software communicates with an external dependency.\n* Ensure that a deprecated library isn't used\n\nThis [blog post](https://sourcery.ai/blog/dependency-rules/) shows a 3-step method of defining dependency rules:\n\n1. Draw a diagram showing the optimal dependencies between your packages.\n2. Phrase some rules in a human language based on the diagram: Which package should depend on which?\n3. Translate the rules into code with Sourcery Rules Generator.\n\n## Create Voldemort Rules\n\nWith a \"voldemort\" template, you can create rules that ensure that a specific name isn't used in your code.\n\nFor example:\n\n* The word `annual` shouldn't be used, because the preferred term is `yearly`.\n* The word `util` shouldn't be used, because it's overly general.\n\nYou can create a \"voldemort\" rule with the command:\n\n```\nsourcery-rules voldemort create\n```\n\n\n\nYou'll be prompted to provide:\n\n* the name that you want to avoid\n\n=>\n\n5 rules will be generated:\n\n* function names\n* function arguments\n* class names\n* variable declarations\n* variable assignments\n\n## Using the Generated Rules\n\nThe generated rules can be used by Sourcery to review your project.\nIf you copy the generated rules into your project's `.sourcery.yaml`, Sourcery will use them automatically.\n\nAll the generated rules have the tag `architecture`. Once you've copied them to your `.sourcery.yaml`, you can run them with:\n\n```\nsourcery review --enable architecture .\n```",
"bugtrack_url": null,
"license": "MIT",
"summary": "Generate architecture rules for Python projects.",
"version": "0.5.0",
"split_keywords": [
"architecture",
"development"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "29965f4ba460c2c62724e6b2cdd55231bda97974e65628995da094b9b46ba197",
"md5": "e98ba1fe2f0afe530e523d49d0f760b1",
"sha256": "d3ad18879460638633e77b7815dc2918408b4b83631827fa431fc514f3324d51"
},
"downloads": -1,
"filename": "sourcery_rules_generator-0.5.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e98ba1fe2f0afe530e523d49d0f760b1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9,<4.0",
"size": 9662,
"upload_time": "2023-01-29T10:51:07",
"upload_time_iso_8601": "2023-01-29T10:51:07.353533Z",
"url": "https://files.pythonhosted.org/packages/29/96/5f4ba460c2c62724e6b2cdd55231bda97974e65628995da094b9b46ba197/sourcery_rules_generator-0.5.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "709d13b79471510ecedd9d8304158b79add1c9d3aff82a6605a4ddf6c6a7a9ff",
"md5": "7d2bfb8b824313ad47c60b0e6f35b4c6",
"sha256": "d62e5b3768f45e46a3dce0d1d90a4b39ad4ca8f1b76381cd17c804e881156f53"
},
"downloads": -1,
"filename": "sourcery_rules_generator-0.5.0.tar.gz",
"has_sig": false,
"md5_digest": "7d2bfb8b824313ad47c60b0e6f35b4c6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9,<4.0",
"size": 8503,
"upload_time": "2023-01-29T10:51:09",
"upload_time_iso_8601": "2023-01-29T10:51:09.099543Z",
"url": "https://files.pythonhosted.org/packages/70/9d/13b79471510ecedd9d8304158b79add1c9d3aff82a6605a4ddf6c6a7a9ff/sourcery_rules_generator-0.5.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-01-29 10:51:09",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "sourcery-ai",
"github_project": "sourcery-rules-generator",
"travis_ci": false,
"coveralls": true,
"github_actions": false,
"lcname": "sourcery-rules-generator"
}
JSON
