# ayapingping-py
**ayapingping-py** generates standard project structure to build applications in Python that follow Clean
Architecture and Feature-Driven Design concept.
> Golang variant: [ayapingping-go](https://github.com/dalikewara/ayapingping-go)
> TypeScript variant: [ayapingping-ts](https://github.com/dalikewara/ayapingping-ts)
## Requirements
- Python>=3.10.12
- Operating systems supporting `/bin/sh` with **POSIX** standards ([WHY?](https://github.com/dalikewara/ayapingping-sh)).
**Linux** and **macOS** should have no issues here as they support it by default. For **Windows** users, consider using WSL instead
## Getting started
### Installation
You can use the `pip install` method:
```bash
pip install ayapingping-py
```
#### Possible issue
If you're facing a warning or an issue like this, for example:
```text
WARNING: The script ayapingping-py is installed in '/your/path/.local/bin' which is not on PATH.
Consider adding this directory to PATH or, if you prefer to suppress this warning, use --no-warn-script-location.
```
Then you can install it using the `--user` option, for example:
```bash
pip install --user --force-reinstall ayapingping-py
```
Or if it doesn't work, you can add the directory containing the scripts to your **PATH** manually.
Open your shell configuration file (e.g., `.bashrc`, `.zshrc`, `.profile`, or similar) and add the following line:
```bash
export PATH=$PATH:/your/path/.local/bin
```
Then, restart your shell or run:
```bash
source ~/.bashrc # or source ~/.zshrc, ~/.profile or similar
```
This will make the changes take effect immediately.
### Usage
To generate a new project, simply run the `ayapingping-py` command:
```bash
ayapingping-py
```
Then enter your project name, the **ayapingping-py** generator will set up the project for you.
> The animated example uses the Golang version, but it essentially follows the same approach
### What's next?
Simply start working on your project and make changes.
## Project Structure
To implement the concept of Clean Architecture and ~~Domain-Driven Design~~ Feature-Driven Design, and to keep them understandable, we structure the project like this:
### main.py
- In this file, you initialize dependencies, injections, and anything required to start and run your application
- You can use the command `venv/bin/python main.py`, `python main.py` or `make start` to run your application
### domain
- The **Domain** represents your primary business model or entity
- Define your main object models or properties for your business here, including database models, DTOs (Data Transfer Objects), etc
- Keep this package as straightforward as possible. Avoid including any code that is not directly related to the model itself
- If a **Feature** imports anything from this location, and you want the **Feature** to be accessible through the `importFeature` or `exportFeature` command
without the risk of missing package errors, **DON'T FORGET** to include them in the `features/yourFeature/dependency.json` file
### features
- A **Feature** encapsulates your main business feature, logic, or service
- Here, you include everything necessary to ensure the proper functioning of the feature
- Please prioritize **Feature-Driven Design**, ensuring that features can be easily adapted and seamlessly integrated and imported into different projects
- If another **Feature** imports anything from this location (the current **Feature**), and you want the current **Feature** to be
accessible through the `importFeature` or `exportFeature` command without the risk of missing package errors, **DON'T FORGET** to include them in the `dependency.json` file
- The `dependency.json` is **OPTIONAL**, and **ONLY USEFUL WHEN** you use the `importFeature` or `exportFeature` command. It serves to define
the **Feature** dependencies and avoids possible missing package errors
- A standard **Feature** comprises the following parts: `delivery`, `repositories`, `usecases` and `utility`
- **delivery**
- Hosts feature handlers like HTTP handlers, gRPC handlers, cron jobs, or anything serving between the client and your application or feature
- For config variables, external clients, or use cases, pass or inject them as dependencies
- **repositories**
- Handles communication with external data resources like databases, cloud services, or external services
- Keep your repositories as simple as possible; avoid adding excessive logic
- If necessary, separate operations into smaller methods
- Changes outside the `repositories` should not affect them (except changes for business domain/model/entity)
- For config variables, database frameworks, or external clients, pass or inject them as dependencies
- **usecases**
- Contains the main feature logic
- Changes outside the `usecases` should not impact them (except changes for business domain/model/entity and repositories)
- For config variables, external clients, or repositories, pass or inject them as dependencies
- **utility**
- Accommodates functions tailored to help with common tasks specifically for the **Feature**—treat them as helpers
- Feel free to adopt your own style as long as it aligns with the core concept
### common
- In this place, you can implement various functions to assist you in performing common tasks—consider them as helpers
- Common functions can be directly called from any location
- If a **Domain** or **Feature** imports anything from this location, and you want the **Feature** to be accessible through
the `importFeature` or `exportFeature` command without the risk of missing package errors, **DON'T FORGET** to include
them in the `features/yourFeature/dependency.json` file
### infra
- This is the location to house infrastructure configurations or scripts to facilitate the deployment of your project on a server or VM
### Make It Your Own
Feel free to create your own style to suit your requirements, as long as you still follow the main architecture concept.
You can create folders such as `migration` to store your database migrations, `tmp` for temporary files, etc.
## Importing Features from Another Project
To seamlessly incorporate or import features from another project, use the `importFeature` command:
```bash
ayapingping-py importFeature [feature_1,feature_2,...] from [/local/project or https://example.com/user/project.git or git@example.com:user/project.git]
```
For example:
```bash
ayapingping-py importFeature example_feature from /path/to/your/project
```
```bash
ayapingping-py importFeature example_feature_1,example_feature_2 from git@github.com:username/project.git
```
### Feature dependency
If your feature relies on external packages, it's crucial to address dependencies properly during the import process.
Failure to import necessary dependencies may result in missing packages. To prevent this, please document your feature
dependencies in the `dependency.json` file. Supported dependencies are limited to the following directories: `domain`, `common`, and `features`.
Ensure that your feature dependencies strictly adhere to these directories, avoiding reliance on other locations.
You can also include any external packages to `externals` param to install them automatically using the `venv/bin/pip install` or `pip install` method.
Example `dependency.json` file:
```json
{
"domains": [
"domain_1.py",
"domain_2.py"
],
"features": [
"feature1",
"feature2"
],
"commons": [
"common_function_1.py",
"common_function_2.py"
],
"externals": [
"python-dotenv==1.0.1",
"mysql-connector-python==8.3.0",
"Flask==3.0.2"
]
}
```
## Other Commands
There are several commands similar to `importFeature` above, such as `importDomain`, `importCommon`, `exportFeature`, `exportDomain`, etc.
They function in the same way, for example:
```bash
ayapingping-py importDomain example.py from /path/to/your/project
```
```bash
ayapingping-py importCommon common_function_1.py from https://example.com/user/project.git
```
For `export` command, the behavior is similar to the `import` command, but now uses `export` as the prefix and `to` instead of
`from` when pointing to the source, for example:
```bash
ayapingping-py exportFeature example_feature to /path/to/your/project
```
For more detail and explanation, please visit [ayapingping-sh](https://github.com/dalikewara/ayapingping-sh)
## Release
### Changelog
Read at [CHANGELOG.md](https://github.com/dalikewara/ayapingping-py/blob/master/CHANGELOG.md)
### Credits
Copyright © 2024 [Dali Kewara](https://www.dalikewara.com)
### License
[MIT License](https://github.com/dalikewara/ayapingping-py/blob/master/LICENSE)
Raw data
{
"_id": null,
"home_page": "",
"name": "ayapingping-py",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.10.12",
"maintainer_email": "",
"keywords": "python,ayapingping,ayapingping-py,framework,structure,design,feature,project,clean-architecture,feature-driven-design,domain-driven-design",
"author": "Dali Kewara",
"author_email": "dalikewara@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/e4/d9/3089602366307879bfe966f1285112ff74e78a77b5e8b9e26f2bdeb449d5/ayapingping-py-4.5.5.tar.gz",
"platform": null,
"description": "# ayapingping-py\n\n\n\n\n\n\n\n\n\n\n\n\n\n**ayapingping-py** generates standard project structure to build applications in Python that follow Clean\nArchitecture and Feature-Driven Design concept.\n\n> Golang variant: [ayapingping-go](https://github.com/dalikewara/ayapingping-go)\n\n> TypeScript variant: [ayapingping-ts](https://github.com/dalikewara/ayapingping-ts)\n\n## Requirements\n\n- Python>=3.10.12\n- Operating systems supporting `/bin/sh` with **POSIX** standards ([WHY?](https://github.com/dalikewara/ayapingping-sh)).\n **Linux** and **macOS** should have no issues here as they support it by default. For **Windows** users, consider using WSL instead\n\n## Getting started\n\n### Installation\n\nYou can use the `pip install` method:\n\n```bash\npip install ayapingping-py\n```\n\n#### Possible issue\n\nIf you're facing a warning or an issue like this, for example:\n\n```text\nWARNING: The script ayapingping-py is installed in '/your/path/.local/bin' which is not on PATH.\nConsider adding this directory to PATH or, if you prefer to suppress this warning, use --no-warn-script-location.\n```\n\nThen you can install it using the `--user` option, for example:\n\n```bash\npip install --user --force-reinstall ayapingping-py\n```\n\nOr if it doesn't work, you can add the directory containing the scripts to your **PATH** manually.\nOpen your shell configuration file (e.g., `.bashrc`, `.zshrc`, `.profile`, or similar) and add the following line:\n\n```bash\nexport PATH=$PATH:/your/path/.local/bin\n```\n\nThen, restart your shell or run:\n\n```bash\nsource ~/.bashrc # or source ~/.zshrc, ~/.profile or similar\n```\n\nThis will make the changes take effect immediately.\n\n### Usage\n\nTo generate a new project, simply run the `ayapingping-py` command:\n\n```bash\nayapingping-py\n```\n\nThen enter your project name, the **ayapingping-py** generator will set up the project for you.\n\n\n\n> The animated example uses the Golang version, but it essentially follows the same approach\n\n### What's next?\n\nSimply start working on your project and make changes.\n\n## Project Structure\n\nTo implement the concept of Clean Architecture and ~~Domain-Driven Design~~ Feature-Driven Design, and to keep them understandable, we structure the project like this:\n\n### main.py\n\n- In this file, you initialize dependencies, injections, and anything required to start and run your application\n- You can use the command `venv/bin/python main.py`, `python main.py` or `make start` to run your application\n\n### domain\n\n- The **Domain** represents your primary business model or entity\n- Define your main object models or properties for your business here, including database models, DTOs (Data Transfer Objects), etc\n- Keep this package as straightforward as possible. Avoid including any code that is not directly related to the model itself\n- If a **Feature** imports anything from this location, and you want the **Feature** to be accessible through the `importFeature` or `exportFeature` command\n without the risk of missing package errors, **DON'T FORGET** to include them in the `features/yourFeature/dependency.json` file\n\n### features\n\n- A **Feature** encapsulates your main business feature, logic, or service\n- Here, you include everything necessary to ensure the proper functioning of the feature\n- Please prioritize **Feature-Driven Design**, ensuring that features can be easily adapted and seamlessly integrated and imported into different projects\n- If another **Feature** imports anything from this location (the current **Feature**), and you want the current **Feature** to be\n accessible through the `importFeature` or `exportFeature` command without the risk of missing package errors, **DON'T FORGET** to include them in the `dependency.json` file\n- The `dependency.json` is **OPTIONAL**, and **ONLY USEFUL WHEN** you use the `importFeature` or `exportFeature` command. It serves to define\n the **Feature** dependencies and avoids possible missing package errors\n- A standard **Feature** comprises the following parts: `delivery`, `repositories`, `usecases` and `utility`\n - **delivery**\n - Hosts feature handlers like HTTP handlers, gRPC handlers, cron jobs, or anything serving between the client and your application or feature\n - For config variables, external clients, or use cases, pass or inject them as dependencies\n - **repositories**\n - Handles communication with external data resources like databases, cloud services, or external services\n - Keep your repositories as simple as possible; avoid adding excessive logic\n - If necessary, separate operations into smaller methods\n - Changes outside the `repositories` should not affect them (except changes for business domain/model/entity)\n - For config variables, database frameworks, or external clients, pass or inject them as dependencies\n - **usecases**\n - Contains the main feature logic\n - Changes outside the `usecases` should not impact them (except changes for business domain/model/entity and repositories)\n - For config variables, external clients, or repositories, pass or inject them as dependencies\n - **utility**\n - Accommodates functions tailored to help with common tasks specifically for the **Feature**\u2014treat them as helpers\n- Feel free to adopt your own style as long as it aligns with the core concept\n\n### common\n\n- In this place, you can implement various functions to assist you in performing common tasks\u2014consider them as helpers\n- Common functions can be directly called from any location\n- If a **Domain** or **Feature** imports anything from this location, and you want the **Feature** to be accessible through\n the `importFeature` or `exportFeature` command without the risk of missing package errors, **DON'T FORGET** to include\n them in the `features/yourFeature/dependency.json` file\n\n### infra\n\n- This is the location to house infrastructure configurations or scripts to facilitate the deployment of your project on a server or VM\n\n### Make It Your Own\n\nFeel free to create your own style to suit your requirements, as long as you still follow the main architecture concept.\nYou can create folders such as `migration` to store your database migrations, `tmp` for temporary files, etc.\n\n## Importing Features from Another Project\n\nTo seamlessly incorporate or import features from another project, use the `importFeature` command:\n\n```bash\nayapingping-py importFeature [feature_1,feature_2,...] from [/local/project or https://example.com/user/project.git or git@example.com:user/project.git]\n```\n\nFor example:\n\n```bash\nayapingping-py importFeature example_feature from /path/to/your/project\n```\n\n```bash\nayapingping-py importFeature example_feature_1,example_feature_2 from git@github.com:username/project.git\n```\n\n### Feature dependency\n\nIf your feature relies on external packages, it's crucial to address dependencies properly during the import process.\nFailure to import necessary dependencies may result in missing packages. To prevent this, please document your feature\ndependencies in the `dependency.json` file. Supported dependencies are limited to the following directories: `domain`, `common`, and `features`.\nEnsure that your feature dependencies strictly adhere to these directories, avoiding reliance on other locations.\nYou can also include any external packages to `externals` param to install them automatically using the `venv/bin/pip install` or `pip install` method.\n\nExample `dependency.json` file:\n\n```json\n{\n \"domains\": [\n \"domain_1.py\",\n \"domain_2.py\"\n ],\n \"features\": [\n \"feature1\",\n \"feature2\"\n ],\n \"commons\": [\n \"common_function_1.py\",\n \"common_function_2.py\"\n ],\n \"externals\": [\n \"python-dotenv==1.0.1\",\n \"mysql-connector-python==8.3.0\",\n \"Flask==3.0.2\"\n ]\n}\n```\n\n## Other Commands\n\nThere are several commands similar to `importFeature` above, such as `importDomain`, `importCommon`, `exportFeature`, `exportDomain`, etc.\nThey function in the same way, for example:\n\n```bash\nayapingping-py importDomain example.py from /path/to/your/project\n```\n\n```bash\nayapingping-py importCommon common_function_1.py from https://example.com/user/project.git\n```\n\nFor `export` command, the behavior is similar to the `import` command, but now uses `export` as the prefix and `to` instead of\n`from` when pointing to the source, for example:\n\n```bash\nayapingping-py exportFeature example_feature to /path/to/your/project\n```\n\nFor more detail and explanation, please visit [ayapingping-sh](https://github.com/dalikewara/ayapingping-sh)\n\n## Release\n\n### Changelog\n\nRead at [CHANGELOG.md](https://github.com/dalikewara/ayapingping-py/blob/master/CHANGELOG.md)\n\n### Credits\n\nCopyright © 2024 [Dali Kewara](https://www.dalikewara.com)\n\n### License\n\n[MIT License](https://github.com/dalikewara/ayapingping-py/blob/master/LICENSE)\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "ayapingping-py generates standard project structure to build applications in Python that follow Clean Architecture and Feature-Driven Design concept",
"version": "4.5.5",
"project_urls": null,
"split_keywords": [
"python",
"ayapingping",
"ayapingping-py",
"framework",
"structure",
"design",
"feature",
"project",
"clean-architecture",
"feature-driven-design",
"domain-driven-design"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d772eb05bfbae81be363aceee980908172ea2780431d1f2f300933915b99654d",
"md5": "3c4e098c36ea4a013ed1ebcd489ec2d9",
"sha256": "64ab9daff69b6d8caef1a09dbeec42b717dacbfdd920cecb08f3a044de31e7a6"
},
"downloads": -1,
"filename": "ayapingping_py-4.5.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3c4e098c36ea4a013ed1ebcd489ec2d9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10.12",
"size": 37227,
"upload_time": "2024-03-18T07:40:43",
"upload_time_iso_8601": "2024-03-18T07:40:43.875670Z",
"url": "https://files.pythonhosted.org/packages/d7/72/eb05bfbae81be363aceee980908172ea2780431d1f2f300933915b99654d/ayapingping_py-4.5.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e4d93089602366307879bfe966f1285112ff74e78a77b5e8b9e26f2bdeb449d5",
"md5": "36f3841ce30ed7ead237b5f05a986d73",
"sha256": "9ab34d252ab7a1054d1ec6863bed26b816f8a227d5926de837b2a29088f2081d"
},
"downloads": -1,
"filename": "ayapingping-py-4.5.5.tar.gz",
"has_sig": false,
"md5_digest": "36f3841ce30ed7ead237b5f05a986d73",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10.12",
"size": 23347,
"upload_time": "2024-03-18T07:40:46",
"upload_time_iso_8601": "2024-03-18T07:40:46.190870Z",
"url": "https://files.pythonhosted.org/packages/e4/d9/3089602366307879bfe966f1285112ff74e78a77b5e8b9e26f2bdeb449d5/ayapingping-py-4.5.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-18 07:40:46",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "ayapingping-py"
}
JSON