instant-python 0.2.0__tar.gz → 0.3.0__tar.gz

instant_python-0.3.0/.github/workflows/release.yml

@@ -0,0 +1,69 @@
+name: Generate Release
+
+on:
+  workflow_dispatch:
+
+jobs:
+  bump-version:
+    if: "!startsWith(github.event.head_commit.message, 'bump:')"
+    runs-on: ubuntu-latest
+    outputs:
+      tag: ${{ steps.bump.outputs.new_tag }}
+    steps:
+      - name: Check out
+        uses: actions/checkout@v3
+        with:
+          token: ${{ secrets.CHANGELOG_TOKEN }}
+          fetch-depth: 0
+
+      - name: Bump version and update changelog
+        uses: commitizen-tools/commitizen-action@master
+        with:
+          github_token: ${{ secrets.CHANGELOG_TOKEN }}
+
+  create-release:
+    needs: bump-version
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out
+        uses: actions/checkout@v3
+        with:
+          token: ${{ secrets.CHANGELOG_TOKEN }}
+          fetch-depth: 0
+
+      - name: Get release tag
+        id: release_tag
+        run: |
+          if [ -z "${{ needs.bump_version.outputs.tag }}" ]; then
+            echo "No tag provided from bump version job. Running fallback command..."
+            git fetch --tags
+            echo "release_tag=$(git describe --tags --abbrev=0)" >> $GITHUB_OUTPUT
+          else
+            echo "Using tag provided from bump version job."
+            echo "release_tag=${{ needs.bump_version.outputs.tag }}" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Extract Changelog for Release
+        id: extract_changelog
+        run: |
+          release="${{ steps.determine_tag.outputs.release_tag }}"
+          echo "Extracting changelog for tag: ${release}"
+          
+          awk -v tag="$release" '
+            BEGIN {flag=0}
+            /^## / {
+              if (flag == 1 && $0 !~ ("^## " tag)) { exit }
+              if ($0 ~ ("^## " tag)) { flag=1 }
+            }
+            flag { print }
+          ' CHANGELOG.md > release_changelog.md
+
+          cat release_changelog.md
+
+      - name: Create release
+        uses: ncipollo/release-action@v1
+        with:
+          token: ${{ secrets.CHANGELOG_TOKEN }}
+          tag: ${{ steps.release_tag.outputs.release_tag }}
+          name: Release ${{ steps.release_tag.outputs.release_tag }}
+          bodyFile: release_changelog.md

{instant_python-0.2.0 → instant_python-0.3.0}/CHANGELOG.md

@@ -1,3 +1,28 @@
+## 0.3.0 (2025-04-11)
+
+### ✨ Features
+
+- **project-generator**: add support for creating user File instances in folder tree
+- **project-generator**: create new File class to model user files
+- **project-generator**: create JinjaEnvironment class to manage independently jinja env
+
+### 🐛 Bug Fixes
+
+- **template**: correct IntValueObject template to call super init
+- **template**: remove unnecessary newline in template import
+- **template**: correct typo in jinja template
+
+### ♻️ Code Refactoring
+
+- **template**: modify all template file types
+- **project-generator**: rename File class to BoilerplateFile to be able to differentiate a normal file introduced by the user and a file of the library that contains boilerplate
+- **cli**: update template command parameter from template_name to template_path
+- **cli**: rename configuration variable name from user_requirements to requirements
+- **prompter**: modify configuration file name from user_requirements.yml to ipy.yml
+- **prompter**: rename UserRequirements to RequirementsConfiguration
+- **project-generator**: rename DefaultTemplateManager to JinjaTemplateManager
+- **project-generator**: delegate jinja env management to JinjaEnvironment in DefaultTemplateManager
+
 ## 0.2.0 (2025-04-08)
 
 ### ✨ Features

{instant_python-0.2.0 → instant_python-0.3.0}/PKG-INFO

@@ -1,7 +1,9 @@
 Metadata-Version: 2.4
 Name: instant-python
-Version: 0.2.0
-Summary: Python automatic project generator
+Version: 0.3.0
+Summary: Instant boilerplate generation for Python projects
+Project-URL: documentation, https://dimanu-py.github.io/instant-python/
+Project-URL: repository, https://github.com/dimanu-py/instant-python/
 Author-email: dimanu-py <diegomtz126@gmail.com>
 License:                                  Apache License
                                    Version 2.0, January 2004
@@ -205,6 +207,10 @@ License:                                  Apache License
            See the License for the specific language governing permissions and
            limitations under the License.
 License-File: LICENSE
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
 Requires-Python: >=3.9
 Requires-Dist: jinja2>=3.1.5
 Requires-Dist: pyyaml>=6.0.2
@@ -261,7 +267,7 @@ as soon as possible. An overview of the features is given below, but you can fin
 [documentation](https://dimanu-py.github.io/instant-python/guide/features/).
 
 - Project slug: Configure the name of the main folder of your project.
-- Source name: Configure the name of the source code of your project.
+- Source name: Configure the name of the source code folder of your project.
 - Description: Include a description about your project.
 - Version: Set the initial version of your project.
 - Author: Set the author of the project.

{instant_python-0.2.0 → instant_python-0.3.0}/README.md

@@ -47,7 +47,7 @@ as soon as possible. An overview of the features is given below, but you can fin
 [documentation](https://dimanu-py.github.io/instant-python/guide/features/).
 
 - Project slug: Configure the name of the main folder of your project.
-- Source name: Configure the name of the source code of your project.
+- Source name: Configure the name of the source code folder of your project.
 - Description: Include a description about your project.
 - Version: Set the initial version of your project.
 - Author: Set the author of the project.

instant_python-0.2.0/docs/getting-started/features.md → instant_python-0.3.0/docs/getting-started/features_overview.md

@@ -1,4 +1,4 @@
-# Features
+# Features Overview
 
 `instant-python` provides a set of commands that allow you to generate different aspects of your Python project, from 
 generating a complete project to add some boilerplate or even create your custom template.
@@ -15,7 +15,7 @@ Create a new project setting up all projects files and configurations.
 Generate the folder structure for your project.
 
 - `ipy folder new`: Generate just the folders and files for your project, without any additional installation.
-- [COMING SOON] `ipy folder template <template>`: Generate the folder structure using a custom template.
+- `ipy folder template <template>`: Generate the folder structure using a custom template.
 
 ## Next steps
 

{instant_python-0.2.0 → instant_python-0.3.0}/docs/getting-started/first-steps.md

@@ -11,5 +11,5 @@ This will display the help message where you could see the available command and
 ## Next steps
 
 Now that you have confirmed you have installed `instant-python` correctly, you can check out an 
-[overview of the available commands](features.md) to see what you can do with the library or jump directly
+[overview of the available commands](features_overview) to see what you can do with the library or jump directly
 to the [guides](../guide/index.md) section to learn how to use the library in more detail.

{instant_python-0.2.0 → instant_python-0.3.0}/docs/getting-started/index.md

@@ -5,7 +5,7 @@ to quickly begin using the library.
 
 - [Installing `instant-python`](installation.md)
 - [First steps after installation](first-steps.md)
-- [Overview of available commands](features.md)
+- [Overview of available commands](features_overview)
 
 If you want to go directly to the guides and learn all the possibilities that the library offers, you can
 check the [Guide](../guide/index.md) section.

{instant_python-0.2.0 → instant_python-0.3.0}/docs/getting-started/installation.md

@@ -1,6 +1,10 @@
 # Installation
 
-To ensure a clean and isolated environment, we recommend installing `instant-python` using a virtual environment.
+!!! important
+For the moment, `instant-python` is only supported in Unix-like systems. Windows support is coming soon.
+
+To ensure a clean and isolated environment, we recommend installing `instant-python` using a virtual environment. At your 
+own risk, you can install it at you system Python installation, but this is not recommended.
 Below are the preferred installation methods.
 
 ## Using `pipx`

{instant_python-0.2.0 → instant_python-0.3.0}/docs/guide/creating-a-project.md

@@ -5,7 +5,7 @@
 One of the main commands you can use with `instant-pyton` is the `project` command. This command
 will allow you to create and configure a complete new project from scratch.
 
-!!! note 
+!!! info 
     The `project` command it won't only create the folder structure of your project, but it will also
     allow you to generate a bunch of boilerplate, install the Python version you want to use, install
     dependencies and even configure a git repository for your project.

{instant_python-0.2.0 → instant_python-0.3.0}/docs/guide/custom-templates.md

@@ -1,4 +1,4 @@
-# Custom Templates [COMING SOON]
+# Custom Templates
 
 Both commands available with `instant-python` allow the option of providing a custom template to generate
 the project folder structure instead of using the default templates provided by the library.
@@ -9,12 +9,20 @@ This custom template must follow a specific structure and syntax to be able to g
 - The first level of the yaml will always be `root`
 - The rest of the hierarchy will be declared as a list of elements with the following structure:
   - `name`: The name of the folder or file to create.
-  - `type`: The type of the element, right now only `directory` is available for custom templates.
-  - `python`: If the directory is a python module to include the `__init__.py` file.
-  - `children`: A list of elements that will be created inside the folder.
+  - `type`: The type of the element, which can be `directory` or `file`.
+  - `python`: **Only for directories**. Set its value to True if the directory is a python module to include the `__init__.py` file, otherwise
+     ignore this field.
+  - `extension`: **Only for files**. The extension of the file to create. If the file do not have an extension, you can ignore
+     this field.
+  - `children`: A list of elements that will be created inside the folder. This can be either another directory or files.
 
 The available templates can be found in the [features](../getting-started/features.md) section. The library
 offers a Domain Driven Design, Clean Architecture and Standard templates.
+
+## Examples
+
+???+ example 
+
 Let's imagine that you want to create a new project using a custom template with Hexagonal Architecture. 
 You can create a yaml file with the following content:
 

{instant_python-0.2.0 → instant_python-0.3.0}/docs/guide/features.md

@@ -3,17 +3,17 @@
 When using the subcommand `new` with either the `project` or `folder` command, you will be able to configure
 different aspects of your project through a set of questions that will guide you through the process.
 
-!!! note
-    Depending on the main command you use, you will be able to configure differnt kind of things. Here
+!!! info
+    Depending on the main command you use, you will be able to configure different kind of things. Here
     is an overview of all the options that can be configured.
 
-
 ## Project slug
 
 Configure the name of the main folder of your project. This name will be used in the _pyproject.toml_ file too.
 
-When writing the project slug, you must convey _pyproject.toml_ conventions, so you should not write spaces
-between words.
+!!! warning
+    When writing the project slug, you must convey _pyproject.toml_ conventions, so you should not write spaces
+    between words.
 
 ## Source name
 
@@ -21,7 +21,6 @@ Configure the name of the source code of your project.
 
 The most typical option for this folder is _src_, but you can change it to whatever you want: _source_, _code_, _app_, etc.
 
-
 ## Description
 
 Include a description about your project that will be included in the _pyproject.toml_ file.
@@ -42,7 +41,8 @@ This value will be included in the _pyproject.toml_ and _LICENSE_ files.
 Choose between _MIT_, _Apache_ or _GPL_ licenses to set your project. By default, 
 it will place you on _MIT_ option to be the most popular license.
 
-If you want to use a different license, unfortunately, you will have to change it manually in the _LICENSE_ file.
+!!! info
+    If you want to use a different license, unfortunately, you will have to change it manually in the _LICENSE_ file.
 
 ## Python version
 
@@ -52,9 +52,13 @@ By default, it will place you on the latest version available.
 ## Dependency manager
 
 Choose between two of the most popular dependencies and project manager for Python: 
+
  - [_uv_](https://docs.astral.sh/uv)
  - [_pdm_](https://pdm-project.org/en/latest/)
 
+These managers will allow you to manage your virtual environment, install dependencies and run tasks in your project. By default, it
+will place you on _uv_ option, as is it the fastest and most lightweight dependency manager available.
+
 ## Git
 
 You will be able to configure your project as a git repository automatically.
@@ -70,9 +74,12 @@ configured for Python projects.
 There are some project templates already configured that you can use to create your project. These templates
 will create the folder structure of your project following a specific pattern.
 
+!!! info
+    These templates do not reflect your architecture, but the folder structure of your project. There is a key difference between these concepts.
+
 ### Domain Driven Design
  
-Follows DDD pattern and screaming architecture. 
+Follows DDD pattern and screaming architecture organization. 
 
 Separates the source code and test folder in bounded contexts and aggregates. 
 Each aggregate will contain the known _domain_, _application_ and _infra_ layers. This template will allow you to create your first bounded context and aggregate. 
@@ -131,26 +138,177 @@ Will create your project with the common pattern of source code and test folder.
 ## Out of the box implementations
 
 When creating a new project, you will be able to include some boilerplate and implementations code
-that will help you to start your project
+that will help you to start your project.
+
+!!! info
+    These implementations are completely subjective and personal. This does not mean that you must implement 
+    them in the same way or that they are the best way to implement them. You can use them as a starting point
+    and iterate them as you need.
 
 ### Value objects and exceptions
 
 Value objects are a common pattern in DDD to encapsulate primitives and encapsulate domain logic. If 
 you choose this option, it will include the following value objects:
 
-- Base ValueObject
-- UUID
-- StringValueObject
-- IntValueObject
+???+ example "Base ValueObject"
+
+    ```python
+    class ValueObject[T](ABC):
+      _value: T
+    
+      def __init__(self, value: T) -> None:
+          self._validate(value)
+          self._value = value
+    
+      @abstractmethod
+      def _validate(self, value: T) -> None: ...
+    
+      @property
+      def value(self) -> T:
+        return self._value
+    
+      @override
+      def __eq__(self, other: object) -> bool:
+          if not isinstance(other, ValueObject):
+            return False
+          return self.value == other.value
+    ```
+
+???+ example "UUID"
+    
+    ```python
+
+    class Uuid(ValueObject[str]):
+        def __init__(self, value: str) -> None:
+            super().__init__(value)
+    
+        def _validate(self, value: str) -> None:
+            if value is None:
+                raise RequiredValueError
+            UUID(value)
+    ```
+
+???+ example "StringValueObject"
+
+    ```python
+    class StringValueObject(ValueObject[str]):
+        def __init__(self, value: str) -> None:
+        super().__init__(value)
+
+    def _validate(self, value: str) -> None:
+        if value is None:
+            raise RequiredValueError
+        if not isinstance(value, str):
+            raise IncorrectValueTypeError
+    ```
+???+ example "IntValueObject"
+
+    ```python
+    class IntValueObject(ValueObject[int]):
+        def __init__(self, value: int) -> None:
+            super().__init__(value)
+
+        def _validate(self, value: int) -> None:
+            if value < 0:
+                raise InvalidNegativeValueError(value)
+    ```
 
 Along with these value objects, it will include a base exception class that you can use to create your own exceptions and
 some common exceptions that you can use in your project:
 
-- Base DomainError
-- IncorrectValueTypeError
-- InvalidIdFormatError
-- InvalidNegativeValueError
-- RequiredValueError
+???+ example "Base DomainError"
+    
+    ```python
+    class DomainError(Exception, ABC):
+        @property
+        @abstractmethod
+        def type(self) -> str: ...
+    
+        @property
+        @abstractmethod
+        def message(self) -> str: ...
+    
+        def to_dict(self) -> dict:
+            return {
+                "type": self.type,
+                "message": self.message,
+            }
+    ```
+
+???+ example "IncorrectValueTypeError"
+
+    ```python
+    T = TypeVar("T")
+    
+    
+    class IncorrectValueTypeError(DomainError):
+        def __init__(self, value: T) -> None:
+            self._message = f"Value '{value}' is not of type {type(value).__name__}"
+            self._type = "incorrect_value_type"
+            super().__init__(self._message)
+    
+        @property
+        def type(self) -> str:
+            return self._type
+    
+        @property
+        def message(self) -> str:
+            return self._message
+    ```
+
+???+ example "InvalidIdFormatError"
+
+    ```python
+    class InvalidIdFormatError(DomainError):
+        def __init__(self) -> None:
+            self._message = "User id must be a valid UUID"
+            self._type = "invalid_id_format"
+            super().__init__(self._message)
+    
+        @property
+        def type(self) -> str:
+            return self._type
+    
+        @property
+        def message(self) -> str:
+            return self._message
+    ```
+
+???+ example "InvalidNegativeValueError"
+
+    ```python
+    class InvalidNegativeValueError(DomainError):
+        def __init__(self, value: int) -> None:
+            self._message = f"Invalid negative value: {value}"
+            self._type = "invalid_negative_value"
+            super().__init__(self._message)
+    
+        @property
+        def type(self) -> str:
+            return self._type
+    
+        @property
+        def message(self) -> str:
+            return self._message
+    ```
+
+???+ example "RequiredValueError"
+    
+    ```python
+    class RequiredValueError(DomainError):
+        def __init__(self) -> None:
+            self._message = "Value is required, can't be None"
+            self._type = "required_value"
+            super().__init__(self._message)
+    
+        @property
+        def type(self) -> str:
+            return self._type
+    
+        @property
+        def message(self) -> str:
+            return self._message
+    ```
 
 ### GitHub actions and workflows
 

{instant_python-0.2.0 → instant_python-0.3.0}/docs/guide/folder-structure.md

@@ -9,7 +9,7 @@ This command has two subcommands that you can use to create a new project:
 
 - `ipy folder new`: will generate a question wizard that will guide you through all steps to create the folders of 
 your project.
-- [COMING SOON] `ipy folder template <template>`: will allow you to use a custom template where you specify the folder structure
+- `ipy folder template <template>`: will allow you to use a custom template where you specify the folder structure
 you want to have.
 
 ## New
@@ -31,25 +31,16 @@ can check in the [features](features.md) section:
 - Default templates
 - Out of the box implementations (value objects, exceptions, GitHub actions, makefile, logger, FastAPI, SQL Alchemy, Alembic, event bus)
 
-[//]: # (## Template)
+## Template
 
-[//]: # ()
-[//]: # (The `template` subcommand will only create the folder structure of the project using a custom template that the user)
+The `template` subcommand will only create the folder structure of the project using a custom template that the user provides.
 
-[//]: # (provides.)
 
-[//]: # ()
-[//]: # (!!! important)
+!!! warning
+    With this option the user will only be able to create directories and empty files. No boilerplate will be available when
+    using a custom template.
 
-[//]: # (    With this option the user will only be able to create directories. No additional configuration will be made and)
-
-[//]: # (    no additional files will be created.)
-
-[//]: # ()
-[//]: # ()
-[//]: # (When using this subcommand you would be able to configure the following out of the box implementations that you)
-
-[//]: # (can check in the [features]&#40;features.md&#41; section:)
+When using this subcommand you would be able to configure the following out of the box implementations that you
+can check in the [features](features.md) section:
 
-[//]: # ()
-[//]: # (- Project slug)
+- Project slug

instant_python-0.3.0/docs/guide/index.md

@@ -0,0 +1,9 @@
+# Guides Overview
+
+Check the available guides to learn all the possibilities that the library offers.
+
+- [Choosing the right command for your needs](when-to-use-commands.md)
+- [Creating and configuring a new project](creating-a-project.md)
+- [Creating only the folder structure](folder-structure.md)
+- [All the available features](features.md)
+- [How to create custom templates](custom-templates.md)

instant_python-0.3.0/docs/guide/when-to-use-commands.md

@@ -0,0 +1,39 @@
+# Choosing the Right Command for Your Needs
+
+When working with `instant-python` you may ask when should you use the `project` or `folder` commands or even
+when you should use the `new` or `template` subcommands. In this section we will try to clarify the differences
+and needs of each command and subcommand.
+
+## Project Command and Subcommands
+
+The `project` command is intended not only to generate the folder structure of your project, but also to
+configure a complete environment.
+
+If you want to set a git repository, install dependencies easily at the start, have GitHub actions, makefile, or
+some other implementation right away, this is the command you should use.
+
+If you want to use some of the [default templates](https://dimanu-py.github.io/instant-python/guide/features/#default-templates) that are
+available in the library or include some default implementations, you would want to use the `new` subcommand. However, if you have a specific 
+folder structure you want to use, and it's not available, or you want a custom version of one of the default templates, then you should use
+the `template` subcommand.
+
+!!! warning
+    Notice that with the `template` subcommand you will have a limitation of not being able to configure all the options that
+    the `new` subcommand offers. You can read more about the available options in the [project command section](./creating-a-project.md).
+
+## Folder Command and Subcommands
+
+The `folder` command is only intended to generate the folder structure of your project. It will not configure any additional aspect
+of the project.
+
+If you just want to generate the folders and some empty files fast and be able to begin configuring your project yourself, this is the command 
+you should use.
+
+If you want to use some of the [default templates](https://dimanu-py.github.io/instant-python/guide/features/#default-templates) that are
+available in the library or include some default implementations, you would want to use the `new` subcommand. However, if you have a specific
+folder structure you want to use, and it's not available, or you want a custom version of one of the default templates, then you should use
+the `template` subcommand.
+
+!!! warning
+    Notice that with the `template` subcommand you will have a limitation of not being able to configure all the options that
+    the `new` subcommand offers. You can read more about the available options in the [project command section](./folder-structure.md).

instant_python-0.3.0/docs/welcome.md

@@ -0,0 +1,57 @@
+![Python](https://img.shields.io/badge/python-3.10%2B-blue?style=for-the-badge&logo=python) ![License](https://img.shields.io/github/license/dimanu-py/instant-python?style=for-the-badge)
+
+# Welcome to Instant Python!
+
+Welcome to the [**Instant Python**](https://github.com/dimanu-py/instant-python-ddd) library, a powerful Python library to quickly
+scaffold a modern Python project with best practices and a clean architecture. This template includes ready-to-use scripts, project
+structure options, and automated setup commands to help you kickstart your Python projects.
+
+## Installation
+
+Install `instant-python` from PyPI:
+
+```bash
+# With pipx
+pipx install instant-python
+```
+
+```bash
+# With pip in pyenv
+pip install instant-python
+```
+
+## Documentation Structure
+
+- [Welcome](./welcome.md)
+- [Getting Started](./getting-started/index.md)
+    - [Installation](./getting-started/installation.md)
+    - [First Steps](./getting-started/first-steps.md)
+    - [Features Overview](./getting-started/features_overview.md)
+- [Guide](./guide/index.md)
+    - [Choosing between templates](./guide/when-to-use-commands.md)
+    - [Creating a new project](./guide/creating-a-project.md)
+    - [Creating a folder structure](./guide/folder-structure.md)
+    - [Features](./guide/features.md)
+    - [Custom Templates](./guide/custom-templates.md)
+- [Contributing](./contributing.md)
+
+## Features
+
+With `instant-python` there is a lot of features you can customize easily so you can start coding on your project
+as soon as possible. An overview of the features is given below, but you can find a more detailed explanation in the
+[documentation](https://dimanu-py.github.io/instant-python/guide/features/).
+
+- Project slug: Configure the name of the main folder of your project.
+- Source name: Configure the name of the source code folder of your project.
+- Description: Include a description about your project.
+- Version: Set the initial version of your project.
+- Author: Set the author of the project.
+- License: Choose between _MIT_, _Apache_ or _GPL_ licenses to set your project.
+- Python version: Select the Python version you want to use for your project between versions 3.13 to 3.10.
+- Dependency manager: Choose between _uv_ or _pdm_ dependency managers.
+- Git: configure your project as a git repository automatically.
+- Default templates: select your project template between Domain Driven Design, Clean Architecture or Standard Project to
+  automatically generate your project folders and files.
+- Out of the box implementations: include some boilerplate and implementations code that will help you to start your project faster.
+  Some of the most popular implementations are value objects, domain error modelling, makefile and Async SQL Alchemy.
+- Dependencies: install dependencies automatically in your project.