Configuration
Configuration file
This app needs minimal configuration, most options default to True. The configuration is stored in a TOML file in a sub-folder of the user's home directory. By default (and currently the only option) this file is stored in ~/.pymaker/config.toml. An example of this file is:
[pymaker]
+Configuration - Pymaker - Easily generate a new Python Project Configuration
Configuration file
This app needs minimal configuration, most options default to True. The configuration is stored in a TOML file in a sub-folder of the user's home directory. By default (and currently the only option) this file is stored in ~/.pymaker/config.toml. An example of this file is:
[pymaker]
author_email = "user@server.com"
author_name = "Python User"
default_license = "MIT"
diff --git a/contributing/index.html b/contributing/index.html
index 3dcb22d4..66212167 100644
--- a/contributing/index.html
+++ b/contributing/index.html
@@ -1,4 +1,4 @@
-Contributing - Python Project Generation Tool Contributing to Py-Maker
Thank you for your interest in contributing to Py-Maker! We welcome all contributions, big or small.
If you are not sure where to start, please take a look at the open issues. If you have an idea for a new feature or would like to report a bug, please open a new issue. You can also check the TODO List for ideas.
I also welcome contributions to the documentation. If you find any errors or would like to suggest improvements, please open a new issue or submit a Pull Request.
I you would like to contribute to the code, but find the requirements below a bit daunting, please feel free to open a discussion and I can help you get started, or even pair on a PR.
Prerequisites
Since this is a Python project, you will need to have Python installed on your machine. You can download the latest version of Python from the official website or using your Operating system's package manager. This project requires Python 3.9 or higher.
I'd recommend using pyenv to manage your Python installations, the pyenv-installer works for Linux and Mac OS X. For Windows, you can use the pyenv-win port. See here for installation instructions.
We also use Poetry to manage our dependencies. You should have this installed as well. You can install Poetry by following the instructions on the Poetry website.
Getting Started
Before you start contributing, please make sure you have read and understood our Code of Conduct and License.
To get started, follow these steps:
- Fork the repository and clone it to your local machine.
- Install the required dependencies (see next section).
- Create a new branch for your changes:
git checkout -b my-new-feature. - Make your changes and commit them:
git commit -am 'Add some feature'. - Push your changes to your fork:
git push origin my-new-feature. - Create a new pull request.
Install Dependencies
Run the following command to install the required dependencies:
$ poetry install
+Contributing - Pymaker - Easily generate a new Python Project Contributing to Py-Maker
Thank you for your interest in contributing to Py-Maker! We welcome all contributions, big or small.
If you are not sure where to start, please take a look at the open issues. If you have an idea for a new feature or would like to report a bug, please open a new issue. You can also check the TODO List for ideas.
I also welcome contributions to the documentation. If you find any errors or would like to suggest improvements, please open a new issue or submit a Pull Request.
I you would like to contribute to the code, but find the requirements below a bit daunting, please feel free to open a discussion and I can help you get started, or even pair on a PR.
Prerequisites
Since this is a Python project, you will need to have Python installed on your machine. You can download the latest version of Python from the official website or using your Operating system's package manager. This project requires Python 3.9 or higher.
I'd recommend using pyenv to manage your Python installations, the pyenv-installer works for Linux and Mac OS X. For Windows, you can use the pyenv-win port. See here for installation instructions.
We also use Poetry to manage our dependencies. You should have this installed as well. You can install Poetry by following the instructions on the Poetry website.
Getting Started
Before you start contributing, please make sure you have read and understood our Code of Conduct and License.
To get started, follow these steps:
- Fork the repository and clone it to your local machine.
- Install the required dependencies (see next section).
- Create a new branch for your changes:
git checkout -b my-new-feature. - Make your changes and commit them:
git commit -am 'Add some feature'. - Push your changes to your fork:
git push origin my-new-feature. - Create a new pull request.
Install Dependencies
Run the following command to install the required dependencies:
$ poetry install
You then need to activate the virtual environment:
$ poetry shell
From here you can start working on the project. If you are using an IDE such as VSCode or PyCharm, you can set the use their Python interpreter setting to use the virtual environment that has just been created.
Using Pip
If you prefer to use pip instead of poetry, you can install the dependencies using the auto-generated requirements-dev.txt file:
$ pip install -r requirements-dev.txt
However, Poetry is the recommended (and only supported) way of developing this project and is tightly integrated with the code and tools.
Linting
I am quite strict about linting and code formatting and have set up a number of pre-commit hooks and tasks to ensure that the code meets the required standards.
Use the poe ruff, poe format and poe mypy tasks regularly. If you use VSCode, install the Ruff andMyPy extensions and set them to run on save. The included .vscode folder has the settings for this.
Install Git Pre-Commit hooks
Please install this if you are intending to contribute to the project. It will check commits locally before they are pushed up to the Repo. The GitHub CI runs the linting checks (and in future probably MyPy as well), and will fail if there are any errors.
$ pre-commit install
diff --git a/future-plans/index.html b/future-plans/index.html
index 8365de43..f1a395a3 100644
--- a/future-plans/index.html
+++ b/future-plans/index.html
@@ -1 +1 @@
-Future Plans - Python Project Generation Tool Future Plans
The below is a list of things I'd like to add to the project in the future, and is kinda a 'work list' for me.
Everything below will be implemented and are in no particular order or importance.
General
- Add a flag to overwrite existing files if the directory exists. Make this require confirmation. Alternately allow overwrite with confirmation if an existing/populated directory is found. Add a force flag to skip confirmation.
I think DO NOT allow this when '.' is specified as this could be disastrous. - Add cmd line options to specify the project name, author, etc. so the user doesn't have to enter them manually.
Not sure if this is needed once we add the CLI parameters to the config file. May be useful for automation though. - Add a command to the CLI template command to show the template files as a tree, marking whether each file/folder is from the internal templates or the user's templates.
- Implement a 'plugin' functionality where we can specify modified/extra files to be added to the generated project. This would also add a command line flag (ie
--django, --pydantic or --fastapi or whatever) to use that plugin, and a config setting to specify using this plugin always. Plugins could be built-in (provided with the package) or user-defined (in the users /pymaker/plugins folder or installable via pip). Have a config setting to specify which plugins are enabled. - Include an optional
vscode settings file in the generated project, optimized for python projects. This could include recommended extensions. - Perhaps add AUTHORS.md skeleton.
- Add a default dockerfile? Maybe a docker-compose file as well- Both for this project and for the generated projects?
- Update the
config CLI command to enable setting/flipping individual config settings from the command line. - check for an existing GitHub repository when the user supplies the repo name and ask for an alternative if it exists.
- add option (probably using the eventual plugin functionality) to create a skeleton
typer CLI app. - if it creates a new remote GitHub repo, print the GitHub URL to the console.
- when creating a github repo, set the
About section to the description field in the pyproject.toml file. Also can set the homepage if specified. Options to add tags?
Bugs
- the
release_text option does not work if the --next-release is specified and corresponds to that release_text version. - no validation on the URI input fields (hompage, repository) which could cause Pooetry to fail to install the package.
Back Burner
These are ideas that I may or may not implement. They are here for reference.
- Modify boolean settings in the config to have the values 'yes', 'no' or 'ask'? This will be a bit lower priority and not sure if it's worth it.
- Add some form of 'extra packages' command line option and config setting to automatically add extra packages to the generated
pyproject.toml file. - Add template GitHub workflows for CI/CD, testing, etc. CodeQL or is that too much (I do use it in most of my repos)?
- Add the
actions/stale action to the generated project.
Refactoring / Code Cleanup
- Refactor the
PyMaker class as its getting a bit messy. Maybe split it into multiple classes with specific responsibilities. - Sort out the nested
if/else statements in PyMaker.get_sanitized_package_name. - split the file copy and template handling functionality into it's own module and have the
PyMaker class use it. - split the
ExitErrors class into an 'errors' module, add more error types if needed and use them throughout the code.
Documentation
- Add usage examples and perhaps a walk-through to the documentation. Maybe with a YouTube video?
- explain how to add more License templates to the 'licenses' module
Testing
- Add testing with Pytest (
IN PROGRESS)
Future Plans - Pymaker - Easily generate a new Python Project Future Plans
The below is a list of things I'd like to add to the project in the future, and is kinda a 'work list' for me.
Everything below will be implemented and are in no particular order or importance.
General
- Add a flag to overwrite existing files if the directory exists. Make this require confirmation. Alternately allow overwrite with confirmation if an existing/populated directory is found. Add a force flag to skip confirmation.
I think DO NOT allow this when '.' is specified as this could be disastrous. - Add cmd line options to specify the project name, author, etc. so the user doesn't have to enter them manually.
Not sure if this is needed once we add the CLI parameters to the config file. May be useful for automation though. - Add a command to the CLI template command to show the template files as a tree, marking whether each file/folder is from the internal templates or the user's templates.
- Implement a 'plugin' functionality where we can specify modified/extra files to be added to the generated project. This would also add a command line flag (ie
--django, --pydantic or --fastapi or whatever) to use that plugin, and a config setting to specify using this plugin always. Plugins could be built-in (provided with the package) or user-defined (in the users /pymaker/plugins folder or installable via pip). Have a config setting to specify which plugins are enabled. - Include an optional
vscode settings file in the generated project, optimized for python projects. This could include recommended extensions. - Perhaps add AUTHORS.md skeleton.
- Add a default dockerfile? Maybe a docker-compose file as well- Both for this project and for the generated projects?
- Update the
config CLI command to enable setting/flipping individual config settings from the command line. - check for an existing GitHub repository when the user supplies the repo name and ask for an alternative if it exists.
- add option (probably using the eventual plugin functionality) to create a skeleton
typer CLI app. - if it creates a new remote GitHub repo, print the GitHub URL to the console.
- when creating a github repo, set the
About section to the description field in the pyproject.toml file. Also can set the homepage if specified. Options to add tags?
Bugs
- the
release_text option does not work if the --next-release is specified and corresponds to that release_text version. - no validation on the URI input fields (hompage, repository) which could cause Pooetry to fail to install the package.
Back Burner
These are ideas that I may or may not implement. They are here for reference.
- Modify boolean settings in the config to have the values 'yes', 'no' or 'ask'? This will be a bit lower priority and not sure if it's worth it.
- Add some form of 'extra packages' command line option and config setting to automatically add extra packages to the generated
pyproject.toml file. - Add template GitHub workflows for CI/CD, testing, etc. CodeQL or is that too much (I do use it in most of my repos)?
- Add the
actions/stale action to the generated project.
Refactoring / Code Cleanup
- Refactor the
PyMaker class as its getting a bit messy. Maybe split it into multiple classes with specific responsibilities. - Sort out the nested
if/else statements in PyMaker.get_sanitized_package_name. - split the file copy and template handling functionality into it's own module and have the
PyMaker class use it. - split the
ExitErrors class into an 'errors' module, add more error types if needed and use them throughout the code.
Documentation
- Add usage examples and perhaps a walk-through to the documentation. Maybe with a YouTube video?
- explain how to add more License templates to the 'licenses' module
Testing
- Add testing with Pytest (
IN PROGRESS)
Python Project Generation Tool Python Project Generation Tool
A fully customizable Python application to bootstrap Poetry-based boilerplate for you to start developing your Python applications quicker! Includes linting and Pytest libraries.
It will create a new directory for your project (or use the current directory), initialise a git repository, create a virtual environment, and install some basic dependencies for Testing, Linting and more. Optionally, it can also create a GitHub repository for you and push the initial commit.
Latest Version : v0.10.1
Testing
The generated project includes pytest and some related plugins to allow you to set up testing straight away.
Write your tests in the tests directory and run them with pytest.
Linting
The generated project includes Ruff for linting and code style formatting. Mypy is installed for type checking. These are set quite strictly by default, but you can edit the tools configuration in the pyproject.toml file.
Customize the generated project
You can add extra or edited files to the generated project by adding them to the ~/.pymaker/template directory. The files in this directory will be copied into the generated project, overwriting any existing files with the same name.
It is also possible to dump the whole template into this folder or the current folder so full customization and even removal of files is possible.
Pre-commit
The generated project uses pre-commit to run some checks on the code before it is committed. This is a great tool to help keep your code clean.
To install pre-commit, run the following command from inside your venv:
$ pre-commit install
+Pymaker - Easily generate a new Python Project Python Project Generation Tool
A fully customizable Python application to bootstrap Poetry-based boilerplate for you to start developing your Python applications quicker! Includes linting and Pytest libraries.
It will create a new directory for your project (or use the current directory), initialise a git repository, create a virtual environment, and install some basic dependencies for Testing, Linting and more. Optionally, it can also create a GitHub repository for you and push the initial commit.
Latest Version : v0.10.2
Testing
The generated project includes pytest and some related plugins to allow you to set up testing straight away.
Write your tests in the tests directory and run them with pytest.
Linting
The generated project includes Ruff for linting and code style formatting. Mypy is installed for type checking. These are set quite strictly by default, but you can edit the tools configuration in the pyproject.toml file.
Customize the generated project
You can add extra or edited files to the generated project by adding them to the ~/.pymaker/template directory. The files in this directory will be copied into the generated project, overwriting any existing files with the same name.
It is also possible to dump the whole template into this folder or the current folder so full customization and even removal of files is possible.
Pre-commit
The generated project uses pre-commit to run some checks on the code before it is committed. This is a great tool to help keep your code clean.
To install pre-commit, run the following command from inside your venv:
$ pre-commit install
pre-commit installed at .git/hooks/pre-commit
GitHub Actions and Configuration
By default the generated project includes a GitHub Actions workflow to run Dependabot to keep your dependencies up to date. There are also standard templates for Pull Request and Issues.
The plan is to add more workflows in the future, for example running tests and more.
Changelog Generator
Once you have at least one GitHub release, you can generate a CHANGELOG.md file automatically from this, using the included github-changelog-md tool.
You can run this manually by running the following command from inside your virtual environment:
$ poe changelog
You need to have a GitHub Personal Access Token set in the config file, see the instructions here for more information.
Community related files
To aid in community building, the generated project includes a CODE_OF_CONDUCT.md file. This is based on the Contributor Covenant standard.
Future releases will include other Community related files (for example an AUTHORS file). There are also blank CONTRIBUTING.md and CHANGELOG.md files. The CHANGELOG.md file can be auto-generated.
Contributing to this Project
For information on how to contribute to the project, see the CONTRIBUTING.md file in the root of the repository or on this website
Installation - Python Project Generation Tool Installation
It is best to install this package globally, rather than in a virtual environment, as it is intended to be used to create new projects. Since we are using Poetry to manage the dependencies, a virtual environment will be created for you anyway specific to each project you are creating.
Release Version
Install the package globally using pip:
$ pip install pyproject-maker
+Installation - Pymaker - Easily generate a new Python Project Installation
It is best to install this package globally, rather than in a virtual environment, as it is intended to be used to create new projects. Since we are using Poetry to manage the dependencies, a virtual environment will be created for you anyway specific to each project you are creating.
Release Version
Install the package globally using pip:
$ pip install pyproject-maker
If you cannot install globally due to permissions, you can install it to your user install directory:
$ pip install --user pyproject-maker
or use pipx (recommended method)
$ pipx install pyproject-maker
Bleeding Edge Version
It is possible to install the latest development version of the package directly from the repository. In most cases this should be safe to do, but it is possible that the development version may not be stable or have bugs. If you are having issues with the development version, please open an issue on the repository.
Use pipx (recommended method):
$ pipx install git+https://github.com/seapagan/py-maker
diff --git a/license/index.html b/license/index.html
index 73916af0..3d064f52 100644
--- a/license/index.html
+++ b/license/index.html
@@ -1 +1 @@
-License - Python Project Generation Tool License
MIT License
Copyright (c) 2023 Grant Ramsay
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
License - Pymaker - Easily generate a new Python Project License
MIT License
Copyright (c) 2023 Grant Ramsay
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
A fully customizable Python application to bootstrap Poetry-based boilerplate for you to start developing your Python applications quicker! Includes linting and Pytest libraries.
It will create a new directory for your project (or use the current directory), initialise a git repository, create a virtual environment, and install some basic dependencies for Testing, Linting and more. Optionally, it can also create a GitHub repository for you and push the initial commit.
Latest Version : v0.10.1
"},{"location":"#testing","title":"Testing","text":"The generated project includes pytest and some related plugins to allow you to set up testing straight away.
Write your tests in the tests directory and run them with pytest.
"},{"location":"#linting","title":"Linting","text":"The generated project includes Ruff for linting and code style formatting. Mypy is installed for type checking. These are set quite strictly by default, but you can edit the tools configuration in the pyproject.toml file.
"},{"location":"#customize-the-generated-project","title":"Customize the generated project","text":"You can add extra or edited files to the generated project by adding them to the ~/.pymaker/template directory. The files in this directory will be copied into the generated project, overwriting any existing files with the same name.
It is also possible to dump the whole template into this folder or the current folder so full customization and even removal of files is possible.
"},{"location":"#pre-commit","title":"Pre-commit","text":"The generated project uses pre-commit to run some checks on the code before it is committed. This is a great tool to help keep your code clean.
To install pre-commit, run the following command from inside your venv:
$ pre-commit install\npre-commit installed at .git/hooks/pre-commit\n
"},{"location":"#github-actions-and-configuration","title":"GitHub Actions and Configuration","text":"By default the generated project includes a GitHub Actions workflow to run Dependabot to keep your dependencies up to date. There are also standard templates for Pull Request and Issues.
The plan is to add more workflows in the future, for example running tests and more.
"},{"location":"#changelog-generator","title":"Changelog Generator","text":"Once you have at least one GitHub release, you can generate a CHANGELOG.md file automatically from this, using the included github-changelog-md tool.
You can run this manually by running the following command from inside your virtual environment:
$ poe changelog\n
You need to have a GitHub Personal Access Token set in the config file, see the instructions here for more information.
"},{"location":"#community-related-files","title":"Community related files","text":"To aid in community building, the generated project includes a CODE_OF_CONDUCT.md file. This is based on the Contributor Covenant standard.
Future releases will include other Community related files (for example an AUTHORS file). There are also blank CONTRIBUTING.md and CHANGELOG.md files. The CHANGELOG.md file can be auto-generated.
"},{"location":"#contributing-to-this-project","title":"Contributing to this Project","text":"For information on how to contribute to the project, see the CONTRIBUTING.md file in the root of the repository or on this website
"},{"location":"changelog/","title":"Changelog","text":""},{"location":"changelog/#changelog","title":"Changelog","text":"This is an auto-generated log of all the changes that have been made to the project since the first release.
This project adheres to Semantic Versioning.
"},{"location":"changelog/#v0102-march-13-2024","title":"v0.10.2 (March 13, 2024)","text":"Closed Issues
- License name is missing in the generated README (#321) by seapagan
- The templates for some generated files need updating (#320) by seapagan
New Features
- Add pytest watcher task (#326) by seapagan
Bug Fixes
- Fix some bugs in the template files and update obsolete information (#325) by seapagan
- Fix missing license name in generated README (#324) by seapagan
Dependency Updates
- Build(deps): bump pydantic from 2.6.3 to 2.6.4 (#323) by dependabot[bot]
Full Changelog | Diff | Patch
"},{"location":"changelog/#v0101-march-12-2024","title":"v0.10.1 (March 12, 2024)","text":"Closed Issues
- Empty string for 'homepage' in
pyproject.html crashes Poetry (#317) by seapagan
Testing
- Add unit tests for the
Settings module (#310) by seapagan
Bug Fixes
- Fix bug where bad homepage field crashes
poetry install (#318) by seapagan
Refactoring
- Convert settings module to use new
get_settings() method (#309) by seapagan
Documentation
- Update Docs to mention previous linting changes (#305) by seapagan
Dependency Updates
- Build(deps): bump simple-toml-settings from 0.5.0 to 0.6.0 (#316) by dependabot[bot]
- Build(deps-dev): bump mypy from 1.8.0 to 1.9.0 (#315) by dependabot[bot]
- Build(deps-dev): bump types-requests from 2.31.0.20240218 to 2.31.0.20240311 (#314) by dependabot[bot]
- Build(deps-dev): bump pytest from 8.1.0 to 8.1.1 (#313) by dependabot[bot]
- Build(deps-dev): bump faker from 24.0.0 to 24.1.0 (#312) by dependabot[bot]
- Build(deps-dev): bump ruff from 0.3.1 to 0.3.2 (#311) by dependabot[bot]
- Build(deps): bump simple-toml-settings from 0.4.0 to 0.5.0 (#307) by dependabot[bot]
- Build(deps-dev): bump ruff from 0.3.0 to 0.3.1 (#306) by dependabot[bot]
Full Changelog | Diff | Patch
"},{"location":"changelog/#v0100-march-06-2024","title":"v0.10.0 (March 06, 2024)","text":"Closed Issues
- When missing the config file, it does not properly read the users Git username/email (#291) by seapagan
Bug Fixes
- Fix bug in post create-file hook (#300) by seapagan
Dependency Updates
- Build(deps-dev): bump mkdocs-material from 9.5.12 to 9.5.13 (#303) by dependabot[bot]
- Build(deps-dev): bump pymdown-extensions from 10.7 to 10.7.1 (#302) by dependabot[bot]
- Build(deps-dev): bump faker from 23.3.0 to 24.0.0 (#301) by dependabot[bot]
Full Changelog | Diff | Patch
"},{"location":"changelog/#v095-march-04-2024","title":"v0.9.5 (March 04, 2024)","text":"Closed Issues
- For standalone app, the suggested GitHub URL is wrong, it should be the same as if the app was a package (#296) by seapagan
- Template deps need updating and template config files need a freshening (#294) by seapagan
- Standalone app should have the ending text changed. (#293) by seapagan
- If creating a standalone,
poetry install should set 'package-mode=false' in the pyproject.toml (#292) by seapagan
Merged Pull Requests
- Fix formatting to new Ruff 3.0 (#289) by seapagan
New Features
- Update deps and template, freshen the template config files. (#297) by seapagan
Testing
- Continue writing tests. (#267) by seapagan
- Add a testing stage to CI with coverage reports from codacy (#266) by seapagan
Bug Fixes
- Ask for repo name and offer to create for both type of projects (#298) by seapagan
- Fix several issues with generating standalone projects (#295) by seapagan
Dependency Updates
- Build(deps-dev): bump pytest from 8.0.2 to 8.1.0 (#290) by dependabot[bot]
- Build(deps-dev): bump ruff from 0.2.1 to 0.3.0 (#288) by dependabot[bot]
- Build(deps-dev): bump mkdocs-autorefs from 0.5.0 to 1.0.1 (#287) by dependabot[bot]
- Build(deps-dev): bump mkdocs-material from 9.5.9 to 9.5.12 (#286) by dependabot[bot]
- Build(deps): bump rich from 13.7.0 to 13.7.1 (#285) by dependabot[bot]
- Build(deps): bump pydantic from 2.6.1 to 2.6.3 (#284) by dependabot[bot]
- Build(deps-dev): bump faker from 23.2.0 to 23.3.0 (#282) by dependabot[bot]
- Build(deps-dev): bump mkdocstrings from 0.24.0 to 0.24.1 (#281) by dependabot[bot]
- Build(deps-dev): bump pytest from 8.0.0 to 8.0.2 (#280) by dependabot[bot]
- Build(deps-dev): bump poethepoet from 0.24.4 to 0.25.0 (#277) by dependabot[bot]
- and 35 more dependency updates
Full Changelog | Diff | Patch
"},{"location":"changelog/#v094-december-11-2023","title":"v0.9.4 (December 11, 2023)","text":"This is a security release that fixes a vulnerability in the 'cryptography' package.
Refactoring
- Update pre commit config to use poetry-export-plugin directly (#203) by seapagan
Dependency Updates
- Build(deps-dev): bump mkdocs-material from 9.4.8 to 9.5.1 (#216) by dependabot[bot]
- Build(deps): bump actions/stale from 8 to 9 (#215) by dependabot[bot]
- Build(deps-dev): bump ruff from 0.1.5 to 0.1.7 (#214) by dependabot[bot]
- Build(deps): bump cryptography from 41.0.5 to 41.0.6 (#213) by dependabot[bot]
- Build(deps-dev): bump pytest-xdist from 3.4.0 to 3.5.0 (#209) by dependabot[bot]
- Build(deps-dev): bump pygments from 2.16.1 to 2.17.2 (#208) by dependabot[bot]
- Build(deps-dev): bump faker from 20.0.3 to 20.1.0 (#206) by dependabot[bot]
- Build(deps): bump rich from 13.6.0 to 13.7.0 (#202) by dependabot[bot]
- Build(deps-dev): bump mkdocstrings from 0.23.0 to 0.24.0 (#201) by dependabot[bot]
- Build(deps-dev): bump poethepoet from 0.24.3 to 0.24.4 (#200) by dependabot[bot]
- and 16 more dependency updates
Full Changelog | Diff | Patch
"},{"location":"changelog/#v093-october-29-2023","title":"v0.9.3 (October 29, 2023)","text":"Refactoring
- Run Ruff on github actions (#174) by seapagan
- Migrate linting and formatting to Ruff (#173) by seapagan
Dependency Updates
- Build(deps-dev): bump faker from 19.10.0 to 19.12.0 (#172) by dependabot[bot]
- Build(deps-dev): bump black from 23.10.0 to 23.10.1 (#171) by dependabot[bot]
- Build(deps-dev): bump pylint from 3.0.1 to 3.0.2 (#170) by dependabot[bot]
- Build(deps-dev): bump mypy from 1.6.0 to 1.6.1 (#168) by dependabot[bot]
- Build(deps-dev): bump pylint-pytest from 1.1.2 to 1.1.3 (#167) by dependabot[bot]
Full Changelog | Diff | Patch
"},{"location":"changelog/#v092-october-24-2023","title":"v0.9.2 (October 24, 2023)","text":"Merged Pull Requests
- Migrate to new changelog generator (#165) by seapagan
Dependency Updates
- Build(deps): bump simple-toml-settings from 0.2.2 to 0.3.0 (#163) by dependabot[bot]
- Build(deps-dev): bump pymdown-extensions from 10.3 to 10.3.1 (#162) by dependabot[bot]
- Build(deps-dev): bump pytest-mock from 3.11.1 to 3.12.0 (#161) by dependabot[bot]
- Build(deps-dev): bump black from 23.9.1 to 23.10.0 (#160) by dependabot[bot]
- Build(deps): bump gitpython from 3.1.37 to 3.1.40 (#159) by dependabot[bot]
- Build(deps-dev): bump types-requests from 2.31.0.8 to 2.31.0.10 (#158) by dependabot[bot]
- Build(deps-dev): bump flake8-type-checking from 2.4.2 to 2.5.1 (#157) by dependabot[bot]
- Build(deps): bump urllib3 from 2.0.6 to 2.0.7 (#156) by dependabot[bot]
- Build(deps-dev): bump mkdocs-material from 9.4.5 to 9.4.6 (#154) by dependabot[bot]
- Build(deps-dev): bump mkdocs-git-revision-date-localized-plugin from 1.2.0 to 1.2.1 (#152) by dependabot[bot]
- and 1 more dependency updates
Full Changelog | Diff | Patch
"},{"location":"changelog/#v091-october-12-2023","title":"v0.9.1 (October 12, 2023)","text":"Bug Fixes
- Remove extra '__init__.py' file (#150) by seapagan
Dependency Updates
- Build(deps-dev): bump faker from 19.8.0 to 19.10.0 (#149) by dependabot[bot]
- Build(deps-dev): bump mypy from 1.5.1 to 1.6.0 (#147) by dependabot[bot]
Full Changelog | Diff | Patch
"},{"location":"changelog/#v090-october-10-2023","title":"v0.9.0 (October 10, 2023)","text":"Merged Pull Requests
- Unlock 'poethepoet' upgrades (#142) by seapagan
New Features
- Migrate settings to my 'simple-toml-settings' library (#146) by seapagan
Dependency Updates
- Build(deps-dev): bump mkdocs-material from 9.4.4 to 9.4.5 (#145) by dependabot[bot]
- Build(deps-dev): bump pylint from 2.17.7 to 3.0.1 (#144) by dependabot[bot]
- Build(deps-dev): bump faker from 19.6.2 to 19.8.0 (#143) by dependabot[bot]
- Build(deps-dev): bump pylint-pydantic from 0.2.4 to 0.3.0 (#139) by dependabot[bot]
- Build(deps-dev): bump mkdocs-material from 9.4.3 to 9.4.4 (#138) by dependabot[bot]
- Build(deps-dev): bump flake8-type-checking from 2.4.1 to 2.4.2 (#137) by dependabot[bot]
- Build(deps-dev): bump types-requests from 2.31.0.7 to 2.31.0.8 (#136) by dependabot[bot]
Full Changelog | Diff | Patch
"},{"location":"changelog/#v080-october-04-2023","title":"v0.8.0 (October 04, 2023)","text":"Merged Pull Requests
- Add help to poe tasks (#130) by seapagan
New Features
- Automatically create a GitHub repository for the new project (#134) by seapagan
Refactoring
- Migrate tomli lib to rtoml (#131) by seapagan
Dependency Updates
- Build(deps-dev): bump mkdocs-material from 9.4.2 to 9.4.3 (#133) by dependabot[bot]
- Build(deps): bump urllib3 from 2.0.4 to 2.0.6 (#132) by dependabot[bot]
- Build(deps): bump rich from 13.5.3 to 13.6.0 (#128) by dependabot[bot]
- Build(deps-dev): bump pylint from 2.17.6 to 2.17.7 (#127) by dependabot[bot]
- Build(deps-dev): bump types-requests from 2.31.0.6 to 2.31.0.7 (#126) by dependabot[bot]
- Build(deps-dev): bump poethepoet from 0.23.0 to 0.24.0 (#125) by dependabot[bot]
Full Changelog | Diff | Patch
"},{"location":"changelog/#v070-october-01-2023","title":"v0.7.0 (October 01, 2023)","text":"Merged Pull Requests
- Improve typing across the package (#115) by seapagan
- Adjust suggested git repo name (#103) by seapagan
New Features
- Implement 'config edit' command (#124) by seapagan
- Add '--bare' option (#123) by seapagan
- Add '--standalone' CLI flag (#113) by seapagan
- Add optional github_token setting (#106) by seapagan
- Store and use GitHub username (#104) by seapagan
Documentation
- Adjust and clarify some docs (#114) by seapagan
- Add a contributing guide (#109) by seapagan
- Add a POE Task to automatically create and update the CHANGELOG.md (#107) by seapagan
- Add MkDocs Tasks to the Documentation (#105) by seapagan
Dependency Updates
- Build(deps): bump pydantic from 2.3.0 to 2.4.2 (#122) by dependabot[bot]
- Build(deps-dev): bump types-requests from 2.31.0.4 to 2.31.0.6 (#120) by dependabot[bot]
- Build(deps-dev): bump pylint from 2.17.5 to 2.17.6 (#119) by dependabot[bot]
- Build(deps-dev): bump types-requests from 2.31.0.3 to 2.31.0.4 (#112) by dependabot[bot]
- Build(deps-dev): bump mkdocs-material from 9.4.0 to 9.4.2 (#111) by dependabot[bot]
- Build(deps-dev): bump poethepoet from 0.22.1 to 0.23.0 (#110) by dependabot[bot]
Full Changelog | Diff | Patch
"},{"location":"changelog/#v062-september-24-2023","title":"v0.6.2 (September 24, 2023)","text":"Closed Issues
- --version flag does not work. (#101) by seapagan
Merged Pull Requests
- Add poe tasks for documentation if mkdocs enabled (#100) by seapagan
Bug Fixes
- Fix #101 (--version flag does not work) (#102) by seapagan
Full Changelog | Diff | Patch
"},{"location":"changelog/#v061-september-23-2023","title":"v0.6.1 (September 23, 2023)","text":"Merged Pull Requests
- Update tool versions in both pre-commit configs (#99) by seapagan
Bug Fixes
- Fix typos and wording in the generated readme (#98) by seapagan
Documentation
- Remove dependency spam from changelog (#97) by seapagan
Dependency Updates
- Build(deps): bump gitpython from 3.1.36 to 3.1.37 (#96) by dependabot[bot]
- Build(deps-dev): bump mkdocs-material from 9.3.2 to 9.4.0 (#95) by dependabot[bot]
- Build(deps-dev): bump types-requests from 2.31.0.2 to 2.31.0.3 (#94) by dependabot[bot]
- Build(deps-dev): bump faker from 19.6.1 to 19.6.2 (#93) by dependabot[bot]
- Build(deps-dev): bump mkdocs from 1.5.2 to 1.5.3 (#92) by dependabot[bot]
- Build(deps-dev): bump mkdocs-material from 9.3.1 to 9.3.2 (#91) by dependabot[bot]
- Build(deps): bump rich from 13.5.2 to 13.5.3 (#90) by dependabot[bot]
Full Changelog | Diff | Patch
"},{"location":"changelog/#v060-september-14-2023","title":"v0.6.0 (September 14, 2023)","text":"New Features
- Auto install and update 'pre commit' (#88) by seapagan
- Add code of conduct to project and the template (#87) by seapagan
- Add Github templates to the default output template (#86) by seapagan
Dependency Updates
- Build(deps): bump actions/stale from 5 to 8 (#89) by dependabot[bot]
Full Changelog | Diff | Patch
"},{"location":"changelog/#v051-september-12-2023","title":"v0.5.1 (September 12, 2023)","text":"New Features
- Add --version command to CLI (#63) by seapagan
Bug Fixes
- Add missing 'requests' library to pyproject.toml (#82) by seapagan
Dependency Updates
- Bump faker from 19.6.0 to 19.6.1 (#85) by dependabot[bot]
- Bump gitpython from 3.1.35 to 3.1.36 (#84) by dependabot[bot]
- Bump mkdocs-material from 9.2.8 to 9.3.1 (#83) by dependabot[bot]
- Bump pymarkdownlnt from 0.9.13.3 to 0.9.13.4 (#80) by dependabot[bot]
- Bump faker from 19.3.1 to 19.6.0 (#79) by dependabot[bot]
- Bump black from 23.7.0 to 23.9.1 (#78) by dependabot[bot]
- Bump pytest from 7.4.0 to 7.4.2 (#77) by dependabot[bot]
- Bump gitpython from 3.1.33 to 3.1.35 (#76) by dependabot[bot]
- Bump pymarkdownlnt from 0.9.13 to 0.9.13.3 (#74) by dependabot[bot]
- Bump mkdocs-material from 9.2.7 to 9.2.8 (#73) by dependabot[bot]
- and 8 more dependency updates
Full Changelog | Diff | Patch
"},{"location":"changelog/#v050-august-31-2023","title":"v0.5.0 (August 31, 2023)","text":"New Features
- Ask for homepage & repository if not standalone (#61) by seapagan
- Update template toml and pre-commit deps (#58) by seapagan
- Override config options from command line (#55) by seapagan
- Check PyPI for existing packages (#46) by seapagan
Bug Fixes
- Fix unable to create standalone app (#60) by seapagan
Refactoring
- Override config options from command line (#55) by seapagan
Documentation
- Update docs for latest additions (#59) by seapagan
Dependency Updates
- Bump mkdocs-material from 9.2.3 to 9.2.6 (#57) by dependabot[bot]
- Bump pymdown-extensions from 10.1 to 10.2.1 (#56) by dependabot[bot]
- Bump pymdown-extensions from 10.1 to 10.2 (#54) by dependabot[bot]
- Bump mkdocs-material from 9.2.3 to 9.2.5 (#53) by dependabot[bot]
- Bump pydantic from 2.1.1 to 2.3.0 (#52) by dependabot[bot]
- Bump faker from 19.3.0 to 19.3.1 (#51) by dependabot[bot]
- Bump mkdocs-material from 9.1.21 to 9.2.3 (#50) by dependabot[bot]
- Bump mypy from 1.5.0 to 1.5.1 (#45) by dependabot[bot]
Full Changelog | Diff | Patch
"},{"location":"changelog/#v045-august-17-2023","title":"v0.4.5 (August 17, 2023)","text":"New Features
- Work on the TODO list. See commits for details (#44) by seapagan
Dependency Updates
- Bump pytest-randomly from 3.14.0 to 3.15.0 (#43) by dependabot[bot]
Full Changelog | Diff | Patch
"},{"location":"changelog/#v044-august-15-2023","title":"v0.4.4 (August 15, 2023)","text":"New Features
- Add mkdocs as an option (#42) by seapagan
Dependency Updates
- Bump poethepoet from 0.21.1 to 0.22.0 (#41) by dependabot[bot]
- Bump pytest-randomly from 3.13.0 to 3.14.0 (#40) by dependabot[bot]
Full Changelog | Diff | Patch
"},{"location":"changelog/#v043-august-13-2023","title":"v0.4.3 (August 13, 2023)","text":"New Features
- Tweak linting (#39) by seapagan
Dependency Updates
- Bump mypy from 1.4.1 to 1.5.0 (#38) by dependabot[bot]
Full Changelog | Diff | Patch
"},{"location":"changelog/#v042-august-10-2023","title":"v0.4.2 (August 10, 2023)","text":" - Added a missing runtime dep (rtoml). It must have been in my venv but not in the
pyproject.toml \ud83d\ude44
Full Changelog | Diff | Patch
"},{"location":"changelog/#v041-august-10-2023","title":"v0.4.1 (August 10, 2023)","text":" - Fixed bug where the first-time config file gets the wrong default template path.
- Update the internal template
pyproject.toml and .pre-commit-config.yaml to use latest dependencies
Full Changelog | Diff | Patch
"},{"location":"changelog/#v040-august-10-2023","title":"v0.4.0 (August 10, 2023)","text":"New Features
- Implement custom template additions (#31) by seapagan
Refactoring
- Implement custom template additions (#31) by seapagan
Dependency Updates
- Bump faker from 19.2.0 to 19.3.0 (#37) by dependabot[bot]
- Bump pygments from 2.15.1 to 2.16.1 (#36) by dependabot[bot]
- Bump mkdocs from 1.5.1 to 1.5.2 (#35) by dependabot[bot]
- Bump rich from 13.5.0 to 13.5.2 (#34) by dependabot[bot]
- Bump mkdocs-minify-plugin from 0.7.0 to 0.7.1 (#33) by dependabot[bot]
Full Changelog | Diff | Patch
"},{"location":"changelog/#v030-july-30-2023","title":"v0.3.0 (July 30, 2023)","text":"New Features
- Add a configuration file (#30) by seapagan
- Use conditional logic in templates (#24) by seapagan
Refactoring
- Use conditional logic in templates (#24) by seapagan
Dependency Updates
- Bump mkdocs-material from 9.1.19 to 9.1.21 (#29) by dependabot[bot]
- Bump mkdocs from 1.4.3 to 1.5.1 (#28) by dependabot[bot]
- Bump pylint from 2.17.4 to 2.17.5 (#26) by dependabot[bot]
- Bump pydantic from 2.0.3 to 2.1.1 (#22) by dependabot[bot]
Full Changelog | Diff | Patch
"},{"location":"changelog/#v021-july-26-2023","title":"v0.2.1 (July 26, 2023)","text":"New Features
- Add a documentation site (#23) by seapagan
Documentation
- Add a documentation site (#23) by seapagan
Full Changelog | Diff | Patch
"},{"location":"changelog/#v020-july-26-2023","title":"v0.2.0 (July 26, 2023)","text":"Refactoring
- Move licenses out of template folder (#21) by seapagan
- Subclass the Rich prompt locally (#20) by seapagan
Dependency Updates
- Bump pytest-asyncio from 0.21.0 to 0.21.1 (#19) by dependabot[bot]
- Bump flake8-type-checking from 2.4.0 to 2.4.1 (#18) by dependabot[bot]
- Bump gitpython from 3.1.31 to 3.1.32 (#17) by dependabot[bot]
- Bump pydantic from 2.0.2 to 2.0.3 (#16) by dependabot[bot]
- Bump mock from 5.0.2 to 5.1.0 (#15) by dependabot[bot]
- Bump faker from 18.11.2 to 19.2.0 (#14) by dependabot[bot]
- Bump poethepoet from 0.20.0 to 0.21.1 (#12) by dependabot[bot]
- Bump pytest-reverse from 1.6.0 to 1.7.0 (#10) by dependabot[bot]
- Bump black from 23.3.0 to 23.7.0 (#9) by dependabot[bot]
- Bump pytest-randomly from 3.12.0 to 3.13.0 (#8) by dependabot[bot]
- and 1 more dependency updates
Full Changelog | Diff | Patch
"},{"location":"changelog/#v010-july-06-2023","title":"v0.1.0 (July 06, 2023)","text":"Merged Pull Requests
- Add base app functionality (#1) by seapagan
New Features
- Customize or remove the Package layout (#5) by seapagan
Refactoring
- Refactor the src template layout and logic (#2) by seapagan
This changelog was generated using github-changelog-md by Seapagan
"},{"location":"configuration/","title":"Configuration","text":""},{"location":"configuration/#configuration-file","title":"Configuration file","text":"This app needs minimal configuration, most options default to True. The configuration is stored in a TOML file in a sub-folder of the user's home directory. By default (and currently the only option) this file is stored in ~/.pymaker/config.toml. An example of this file is:
[pymaker]\nauthor_email = \"user@server.com\"\nauthor_name = \"Python User\"\ndefault_license = \"MIT\"\ngithub_username = \"githubuser\" # optional\ngithub_token = \"ghp_1234567890abcdefghij\" # optional\ngithub_protocol = \"ssh\"\ninclude_linters = true\ninclude_mkdocs = true\ninclude_testing = true\ninstall_pre_commit = true\nschema_version = \"1.0\" # for internal use, generally don't change this\ntemplate_folder = \"/home/user/.pymaker/template\"\nuse_default_template = true\nuse_git = true\ncreate_remote = true\n
If this file does not exist, it will be created on first run. The app will ask for the values of author_name, author_email, default_license and github_username. For author_name and author_email it will try to use the current global git user name and email if they are set as defaults, though the user can override these.
"},{"location":"configuration/#configuration-options","title":"Configuration options","text":"The following options are available for configuring Py-Maker:
author_email: The email address of the author.author_name: The name of the author.default_license: The default license to use for the project.github_username: The GitHub username of the author [optional].github_token: The GitHub Personal Access Token of the author [optional]. See below for more information.github_protocol: The protocol to use for GitHub, either ssh or https, defaults to ssh which means that the user will need to have set up an SSH key with GitHub and added it to their account. If you wish to use HTTPS, you will be asked for your GitHub password every time you push to the remote repository.include_linters: Whether to include linters in the project, defaults to trueinclude_mkdocs: Whether to include MkDocs in the project, defaults to trueinclude_testing: Whether to include testing in the project, defaults to trueinstall_pre_commit: Whether to install pre-commit hooks, defaults to trueschema_version: The version of the configuration schema. This should not be modified by hand. Currently, and until version 1.0 is released, this is set to \"none\" to indicate that the schema is not yet stable.template_folder: The path to the template folder.use_default_template: Whether to use the default template, defaults to trueuse_git: Whether to use Git for version control, defaults to truecreate_remote: Whether to create a remote repository on GitHub, defaults to true
All of the boolean options are set to true by default. The template_folder is set to the default template folder, which is ~/.pymaker/template. The schema_version is for internal use, and should not be changed by the user.
"},{"location":"configuration/#view-configuration","title":"View configuration","text":"You can list the current configuration with the command:
$ pymaker config show\n
"},{"location":"configuration/#edit-the-configuration-file","title":"Edit the configuration file","text":"You can edit the configuration file with the command:
$ pymaker config edit\n
This will open the configuration file in your default editor. Under linux it will try to use xdg-open to open the file, and if that fails, it will try to use a few different editors until it finds one that works. Under Windows and Mac it will try to use the default editor.
You may also edit the configuration file manually, by default it is stored in ~/.pymaker/config.toml.
"},{"location":"configuration/#set-configuration","title":"Set configuration","text":"The configuration is set the first time you run the app, but you can change these defaults at any time using the command:
$ pymaker config change\n
The latter command will prompt you for the values of Author name, Author Email, Default License and GitHub Username, then update the configuration file.
"},{"location":"configuration/#add-a-github-personal-access-token","title":"Add a GitHub Personal Access Token","text":"This app is able to create a new GitHub repository for you. To do this, it will need a GitHub Personal Access Token. You can create a new token by going to GitHub Personal Access Tokens and clicking on the \"Generate new token\" button. Use the 'Classic' token option unless you really need more control. Unless you want to use the token on Private repositories, you should check the public_repo option and leave all the other permissions unchecked (this tool does not yet have the option to create a private repository). Give it a name (for your reference only) and chose an expiry date. You can choose never to expire, but this is not recommended. Once you have created the token, copy it (it will only be shown once, so make sure you copy it now). Then run the command:
$ pymaker config token\n
This will accept the token and store it in the configuration file. You can change the token at any time by running the same command again.
NEVER PUSH THE CONFIG FILE TO A REPOSITORY!!!
This shouldnt ever happen since the file is stored in the user's home directory, but it is worth mentioning. If you didn't choose any extra permissions, then the worst that can happen is that someone can use your token to create a new repository. This token is READ-ONLY, so it can't be used to do anything malicious, but it is still a good idea to keep it secret.
"},{"location":"configuration/#manually-editing-the-configuration-file","title":"Manually editing the configuration file","text":"The configuration file is stored in TOML format, and can be edited manually if you wish. The file is stored in ~/.pymaker/config.toml by default. The configuration file is created on first run, so if you have not run the app yet, you will need to create the file manually.
"},{"location":"contributing/","title":"Contributing","text":""},{"location":"contributing/#contributing-to-py-maker","title":"Contributing to Py-Maker","text":"Thank you for your interest in contributing to Py-Maker! We welcome all contributions, big or small.
If you are not sure where to start, please take a look at the open issues. If you have an idea for a new feature or would like to report a bug, please open a new issue. You can also check the TODO List for ideas.
I also welcome contributions to the documentation. If you find any errors or would like to suggest improvements, please open a new issue or submit a Pull Request.
I you would like to contribute to the code, but find the requirements below a bit daunting, please feel free to open a discussion and I can help you get started, or even pair on a PR.
"},{"location":"contributing/#prerequisites","title":"Prerequisites","text":"Since this is a Python project, you will need to have Python installed on your machine. You can download the latest version of Python from the official website or using your Operating system's package manager. This project requires Python 3.9 or higher.
I'd recommend using pyenv to manage your Python installations, the pyenv-installer works for Linux and Mac OS X. For Windows, you can use the pyenv-win port. See here for installation instructions.
We also use Poetry to manage our dependencies. You should have this installed as well. You can install Poetry by following the instructions on the Poetry website.
"},{"location":"contributing/#getting-started","title":"Getting Started","text":"Before you start contributing, please make sure you have read and understood our Code of Conduct and License.
To get started, follow these steps:
- Fork the repository and clone it to your local machine.
- Install the required dependencies (see next section).
- Create a new branch for your changes:
git checkout -b my-new-feature. - Make your changes and commit them:
git commit -am 'Add some feature'. - Push your changes to your fork:
git push origin my-new-feature. - Create a new pull request.
"},{"location":"contributing/#install-dependencies","title":"Install Dependencies","text":"Run the following command to install the required dependencies:
$ poetry install\n
You then need to activate the virtual environment:
$ poetry shell\n
From here you can start working on the project. If you are using an IDE such as VSCode or PyCharm, you can set the use their Python interpreter setting to use the virtual environment that has just been created.
"},{"location":"contributing/#using-pip","title":"Using Pip","text":"If you prefer to use pip instead of poetry, you can install the dependencies using the auto-generated requirements-dev.txt file:
$ pip install -r requirements-dev.txt\n
However, Poetry is the recommended (and only supported) way of developing this project and is tightly integrated with the code and tools.
"},{"location":"contributing/#linting","title":"Linting","text":"I am quite strict about linting and code formatting and have set up a number of pre-commit hooks and tasks to ensure that the code meets the required standards.
Use the poe ruff, poe format and poe mypy tasks regularly. If you use VSCode, install the Ruff andMyPy extensions and set them to run on save. The included .vscode folder has the settings for this.
"},{"location":"contributing/#install-git-pre-commit-hooks","title":"Install Git Pre-Commit hooks","text":"Please install this if you are intending to contribute to the project. It will check commits locally before they are pushed up to the Repo. The GitHub CI runs the linting checks (and in future probably MyPy as well), and will fail if there are any errors.
$ pre-commit install\npre-commit installed at .git/hooks/pre-commit\n
This will ensure that all code meets the required linting standard before being committed.
"},{"location":"contributing/#run-pre-commit-manually","title":"Run pre-commit manually","text":"You can run these checks manually on all staged files using the below command :
poe pre\n
"},{"location":"contributing/#testing","title":"Testing","text":"We are using pytest for testing.
At the moment the test framework is set up but we only have about 50% coverage. We will be adding more tests as we go along - and most definitely welcome any contributions to this area!
If you add any new features, please add tests for them. This will help us to ensure that the code is working as expected and will prevent any regressions. Currently we are not enforcing this until we have better coverage of the code - however if you break any existing tests, the CI will fail.
There is a task set up to run tests:
$ poe test\n
And run a watcher to automatically re-run the tests when files change:
$ poe test:watch\n
You can also run the tests manually using the following command:
$ pytest\n
The task is set up so we can automatically add other options in the future.
"},{"location":"contributing/#changelog","title":"Changelog","text":"The changelog is automatically generated, using this project, so please do not edit it manually.
For maintainers, there is a POE task that will run this and update the changelog file.
$ poe changelog\n
You would also need to add a GitHub Personal Access Token to a local config file as usual. See the section in the Documentation for information.
However, you should NOT include a change to the CHANGELOG.md file in any Pull Requests. This will be handled by the maintainers when a new release is made. Your GitHub username will be added to the changelog automatically beside your PR.
"},{"location":"contributing/#convenience-tasks","title":"Convenience Tasks","text":"There are a few other convenience tasks that can be run using the poe command. These are defined in the pyproject.toml file.
Each of these tasks can have extra options added which will be passed to the underlying tool.
Run mypy on the code base in strict mode:
$ poe mypy\n
Format the code using ruff format:
$ poe format\n
Lint the code using ruff:
$ poe ruff\n
Check the Markdown:
$ poe markdown\n
Run ruff, mypy and format at the same time:
$ poe lint\n
"},{"location":"contributing/#documentation-tasks","title":"Documentation Tasks","text":"These are to help with developing and updating the documentation.
poe docs:serve - Serve the MkDocs locally for testing and developmentpoe docs:serve:all - Same as above, but opens to all interfaces so you can view it on other devices on your networkpoe docs:build - Build the MkDocs site into the dist folderpoe docs:publish - Publish the docs to your GitHub pages. Note that only those with write-access to this repo can do this.
"},{"location":"contributing/#guidelines","title":"Guidelines","text":"Here are some guidelines to follow when contributing to github-changelog-md:
- Follow the PEP 8 style guide. The pre-commit hooks will check for this. We are using the Ruff Formatter.
- Fix any linting errors or warnings. The pre-commit hooks will check for this also. Ruff is installed and set to pretty strict settings. Ruff now replaces all the original linters that were installed. There is also a Markdown linter.
- MyPy is installed and we are using type hints. Please try to add type hints to your code. If you see any areas of the code that are missing type hints, please feel free to open a PR and add them \ud83d\ude01!
- Write clear and concise commit messages.
- Write tests for your code.
- Make sure your code passes all existing and new tests before submitting a pull request.
- Document your code using docstrings. This project uses the Google Docstring Spec though at this time is a bit slack on listing the Args and Returns. I will be adding these in as I go along so feel free to add them in if you are contributing .
- If you add or change any functionality, please update the documentation accordingly.
- Use GitHub issues to report bugs or suggest new features.
If you are using VSCode, there is a config file in the .vscode folder that will help you to follow these guidelines. You may need to install some extensions to get the most out of it. I'll add a list of recommended extensions here soon. The Python, MyPy and Ruff ones are very helpful (the included .vscode folder helps configure these).
"},{"location":"contributing/#contact","title":"Contact","text":"If you have any questions or need help with contributing, please contact me @seapagan on GitHub. You can also use the GitHub Discussions feature.
Happy contributing!
"},{"location":"future-plans/","title":"Future Plans","text":""},{"location":"future-plans/#future-plans","title":"Future Plans","text":"The below is a list of things I'd like to add to the project in the future, and is kinda a 'work list' for me.
Everything below will be implemented and are in no particular order or importance.
"},{"location":"future-plans/#general","title":"General","text":" - Add a flag to overwrite existing files if the directory exists. Make this require confirmation. Alternately allow overwrite with confirmation if an existing/populated directory is found. Add a force flag to skip confirmation.
I think DO NOT allow this when '.' is specified as this could be disastrous. - Add cmd line options to specify the project name, author, etc. so the user doesn't have to enter them manually.
Not sure if this is needed once we add the CLI parameters to the config file. May be useful for automation though. - Add a command to the CLI template command to show the template files as a tree, marking whether each file/folder is from the internal templates or the user's templates.
- Implement a 'plugin' functionality where we can specify modified/extra files to be added to the generated project. This would also add a command line flag (ie
--django, --pydantic or --fastapi or whatever) to use that plugin, and a config setting to specify using this plugin always. Plugins could be built-in (provided with the package) or user-defined (in the users /pymaker/plugins folder or installable via pip). Have a config setting to specify which plugins are enabled. - Include an optional
vscode settings file in the generated project, optimized for python projects. This could include recommended extensions. - Perhaps add AUTHORS.md skeleton.
- Add a default dockerfile? Maybe a docker-compose file as well- Both for this project and for the generated projects?
- Update the
config CLI command to enable setting/flipping individual config settings from the command line. - check for an existing GitHub repository when the user supplies the repo name and ask for an alternative if it exists.
- add option (probably using the eventual plugin functionality) to create a skeleton
typer CLI app. - if it creates a new remote GitHub repo, print the GitHub URL to the console.
- when creating a github repo, set the
About section to the description field in the pyproject.toml file. Also can set the homepage if specified. Options to add tags?
"},{"location":"future-plans/#bugs","title":"Bugs","text":" - the
release_text option does not work if the --next-release is specified and corresponds to that release_text version. - no validation on the URI input fields (hompage, repository) which could cause Pooetry to fail to install the package.
"},{"location":"future-plans/#back-burner","title":"Back Burner","text":"These are ideas that I may or may not implement. They are here for reference.
- Modify boolean settings in the config to have the values 'yes', 'no' or 'ask'? This will be a bit lower priority and not sure if it's worth it.
- Add some form of 'extra packages' command line option and config setting to automatically add extra packages to the generated
pyproject.toml file. - Add template GitHub workflows for CI/CD, testing, etc. CodeQL or is that too much (I do use it in most of my repos)?
- Add the
actions/stale action to the generated project.
"},{"location":"future-plans/#refactoring-code-cleanup","title":"Refactoring / Code Cleanup","text":" - Refactor the
PyMaker class as its getting a bit messy. Maybe split it into multiple classes with specific responsibilities. - Sort out the nested
if/else statements in PyMaker.get_sanitized_package_name. - split the file copy and template handling functionality into it's own module and have the
PyMaker class use it. - split the
ExitErrors class into an 'errors' module, add more error types if needed and use them throughout the code.
"},{"location":"future-plans/#documentation","title":"Documentation","text":" - Add usage examples and perhaps a walk-through to the documentation. Maybe with a YouTube video?
- explain how to add more License templates to the 'licenses' module
"},{"location":"future-plans/#testing","title":"Testing","text":" - Add testing with Pytest (
IN PROGRESS)
"},{"location":"installation/","title":"Installation","text":"It is best to install this package globally, rather than in a virtual environment, as it is intended to be used to create new projects. Since we are using Poetry to manage the dependencies, a virtual environment will be created for you anyway specific to each project you are creating.
"},{"location":"installation/#release-version","title":"Release Version","text":"Install the package globally using pip:
$ pip install pyproject-maker\n
If you cannot install globally due to permissions, you can install it to your user install directory:
$ pip install --user pyproject-maker\n
or use pipx (recommended method)
$ pipx install pyproject-maker\n
"},{"location":"installation/#bleeding-edge-version","title":"Bleeding Edge Version","text":"It is possible to install the latest development version of the package directly from the repository. In most cases this should be safe to do, but it is possible that the development version may not be stable or have bugs. If you are having issues with the development version, please open an issue on the repository.
Use pipx (recommended method):
$ pipx install git+https://github.com/seapagan/py-maker\n
Using pip:
$ pip install git+https://github.com/seapagan/py-maker\n
You can also use the --user flag for pip if you do not have permissions to install globally. This is NOT needed for pipx.
Lastly, you can clone the repository and install from the local copy:
$ git clone https://github.com/seapagan/py-maker\n$ cd py-maker\n$ pip install .\n
"},{"location":"license/","title":"License","text":"MIT License
Copyright (c) 2023 Grant Ramsay
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
"},{"location":"tasks/","title":"Task Runner","text":"The task-runner Poe the Poet is installed in the new project as a development dependency which allows us to run simple tasks (similar to npm or yarn scripts).
These are run (from within the virtual environment) using the poe command and then the script name, for example:
$ poe pre\n
To get a list of all available tasks with a description, run:
$ poe\n
You can define your own, but there are currently several specific ones provided in the new project:
pre : Run pre-commit run --all-filesruff: Run Ruff linter on all Python files in the project.format: Run Ruff Formatter on all Python files in the project.mypy : Run MyPy type-checker on all Python files in the project.-
markdown : Run pymarkdown on all markdown files in the project.
-
lint = Runs ruff, formatter, mypy, markdown in sequence
If you selected to install MkDocs with this project, then there are some extra tasks to help with that:
docs:publish : Deploy the documentation to GitHub pages.docs:build : Build the documentation locally.docs:serve : Serve the documentation locally. Useful during development.docs:serve:all : As above, but allows access from other devices on the network.
There is also a task to run the tests if they were selected:
$ poe test\n
And run a watcher to automatically re-run the tests when files change:
$ poe test:watch\n
Finally, you can automatically generate your CHANGELOG.md file using:
$ poe changelog\n
The changelog uses my Markdown Changelog Generator tool to generate the changelog, check the documentation for that tool for more information.
These tasks are all defined in the pyproject.toml file in the [tool.poe.tasks] section. Take a look at this file if you want to add or remove tasks.
"},{"location":"usage/","title":"Using PyMaker","text":""},{"location":"usage/#create-a-new-project","title":"Create a new project","text":"To create a new project, run the following command:
$ pymaker new <project-folder>\n
This will create a new directory with the name you provide.
You can create a new project in the current directory by using . as the project folder name. This must be an empty directory:
$ mkdir test-project\n$ cd test-project\n$ pymaker new .\n
The App will then run the steps needed to get you started quickly:
- Copy the template files into the new directory
- Initialise a git repository
- Commit the boilerplate to Git
You will be asked a series of questions to customise the new project.
"},{"location":"usage/#choose-a-package-name-and-description","title":"Choose a package name and description","text":"When it asks \"Package Name?\" you can choose two variants :
- If you are creating a standard Python package that can optionally be uploaded to PyPI, enter a package name here. Note that underscores (\"_\") must be used as opposed to dashes (\"-\") to comply with Python package naming rules. Default is the project folder name with underscores replacing dashes, spaces or dots.
- For a stand-alone tool that will not be uploaded to PyPI, or is not a library, enter '-' for the package name. In this case the
main.py will just be placed in the project root and no package folder will be created or referenced. You can also specify --standalone on the command line to skip this question.
For option 1 above, the App will check if the package name is available on PyPI or if it has already been used. In the latter case, you will be asked to choose another name.
"},{"location":"usage/#command-line-options","title":"Command line options","text":"There are a few command line options that can be used to customise the build. Command line options override any settings in the config file.
For example, if use_git = false is set in the config file, then passing --git on the command line will override this and initialise a Git repository.
"},{"location":"usage/#-y-or-yes","title":"-y or --yes","text":"Accept all defaults and do not ask any questions.
"},{"location":"usage/#-git-no-git","title":"--git / --no-git","text":"Initialise a Git repository. Default is True unless use_git = false is set in the config file or --no-git is passed on the command line.
"},{"location":"usage/#-test-no-test","title":"--test / --no-test","text":"Create a test directory and add the pytest dependency plus a few related plugins to the pyproject.toml file. Default is True unless include_testing = false is set in the config file or --no-test is passed on the command line.
"},{"location":"usage/#-lint-no-lint","title":"--lint / --no-lint","text":"Add linting dependencies and configuration to the pyproject.toml file. Default is True unless include_linters = false is set in the config file or --no-lint is passed on the command line.
"},{"location":"usage/#-docs-no-docs","title":"--docs / --no-docs","text":"Add MkDocs and some plugins to the pyproject.toml file. Default is True unless include_mkdocs = false is set in the config file or --no-docs is passed on the command line.
If you choose to run poetry automatically, this will also add a customized mkdocs.yml file and create a new default MkDocs site in the docs folder. Some useful plugins are also installed and added to the mkdocs.yml file.
"},{"location":"usage/#-github-no-github","title":"--github / --no-github","text":"Create a GitHub repository and push the initial commit. Default is True unless create_remote = false is set in the config file or --no-github is passed on the command line. This option needs a GitHub Personal Access Token to be set in the config file, see here
"},{"location":"usage/#-standalone","title":"--standalone","text":"Generate a stand-alone script instead of a package. This will place the main.py file in the project root and not create a package folder. This is useful for creating a single script that can be run from the command line. this is equivalent to entering - for the package name.
"},{"location":"usage/#-bare","title":"--bare","text":"Generate a project without Testing, linting or documentation libraries and configurations. It will also NOT initialise a Git repository. Currently there is no config file option to do this automatically, you must use the command line option.
"},{"location":"usage/#run-poetry-install-automatically","title":"Run poetry install automatically","text":"You will be asked if you want to run poetry install automatically. This will create a virtual environment and install the dependencies, plus also create a bare MkDocs site and configuration. This is the recommended option.
You will still need to run poetry shell to activate the virtual environment from inside the new project folder.
"},{"location":"usage/#start-developing","title":"Start developing","text":"You should now change into the new directory, install dependencies and activate the virtual environment:
$ cd <project-folder>\n$ poetry install # if not done automatically already\n$ poetry shell\n
Now, you can start developing
"},{"location":"usage/#example-run","title":"Example run","text":"$ pymaker new secret-docs\nPyMaker - Generate a Python project skeleton.\n\nCreating a new project at /home/bathroom/secret-docs\n\nName of the Application? (Secret Docs):\nPackage Name? (Use '-' for standalone script) (secret_docs):\nDescription of the Application?: Store all the Bigly amount of secret documents\nI have in the bathroom\n\nAuthor Name? (): Orange Tango\nAuthor Email? (): bigly@spraytan.org\nApplication License? [None/Apache2/BSD3/BSD2/GPL2/GPL3/LGPL/MIT/MPL2/CDDL/EPL2] (MIT):\n\nCreating a New Python app with the below settings :\n\n Description : Store all the Bigly amount of secret documents I have in the\n bathroom\n Package Name : secret_docs\n Author : Orange Tango\n Email : bigly@straytan.org\n License : MIT\n Project Dir : /home/bathroom/secret-docs\n Name : Secret Docs\n Standalone : False\n\nIs this correct? [y/n] (y):\n\n--> Creating project folder ... Done\n\nShould I Run 'poetry install' now? [y/n] (y):\nCreating virtualenv secret-docs in /home/bathroom/secret-docs/.venv\nUpdating dependencies\nResolving dependencies... (11.6s)\n\nPackage operations: 103 installs, 1 update, 0 removals\n\n \u2022 Installing lazy-object-proxy (1.9.0)\n \u2022 Installing six (1.16.0)\n\n <snippy snip>\n\n \u2022 Installing pytest-xdist (3.3.1)\n \u2022 Installing tryceratops (2.3.2)\n\nWriting lock file\n\nInstalling the current project: secret-docs (0.1.0)\n\n--> Creating MkDocs project\nINFO - Writing config file: ./mkdocs.yml\nINFO - Writing initial docs: ./docs/index.md\n\n--> Creating Git repository ... Done\n\n--> Project created successfully.\n\nNext steps:\n\n1. Change to the project directory:\n2. Install the dependencies if not done above (creates a virtual environment):\n $ poetry install\n3. Activate the virtual environment:\n $ poetry shell\n4. Run the application:\n $ secret-docs\n5. Code!\n\nSee the README.md file for more information.\n
"},{"location":"template/internal/","title":"The Internal Template","text":"By default, the generated application will have a basic template that you can use to get started, this template is stored inside the package itself. It will contain all you need to get started, including a basic README.md file.
The dependency management is handled by Poetry, and we include a pyproject.toml file with several useful dependencies:
- PyTest for testing, along with several useful plugins.
- Ruff for linting and formatting. This replaces the need for
flake8, black, isort and more. The default pyproject.toml contains a quite strict configuration by default, but you can modify it to suit your needs. - MyPy for static type checking.
- pre-commit for running checks before committing code.
The pyproject.toml contains a useable configuration for all of these tools, but you can modify it to suit your needs.
It also contains several tasks for running the tests, linting, formatting and more. These use the Poe The Poet Poetry extension see Task Runner for more information.
"},{"location":"template/modify/","title":"Adding or Modifying files in the template","text":"If you wish to add or change specific files in the template, you can do so by adding them to the ~/.pymaker/template folder. The files (and folders) in this folder will be copied to the root of the project when the template is generated.
Files in this global template folder will override any files in the default template, so you can for example change the README.md file, add to the .gitignore or even add a complete extra folder structure.
If you want to do a major change to the template, you can actually dump the default template to this folder and modify or delete files as you see fit. See the next section for more information on how to do this.
"},{"location":"template/replace/","title":"Replacing the Default Template","text":""},{"location":"template/replace/#dump-the-default-template","title":"Dump the Default Template","text":"Should you wish to heavily modify the default template, or even replace it completely, you can do so by dumping the default template to the ~/.pymaker/template folder. This will copy all files from the default template to the global template folder, where you can modify or delete them as you see fit.
To do this, run the following command:
$ pymaker template dump\n
This will copy the default template to the global template folder (~/.pymaker/template). You can then modify or delete files as you see fit.
Running this command will ask you if you wish to set this exported template as the default template. It will then ask you if you want to disable the internal template. If you answer yes, then the internal template will be disabled, and ONLY the exported template will be used instead. Otherwise, both will still be used with the exported template taking precedence.
"},{"location":"template/replace/#change-the-location-of-the-template-folder","title":"Change the location of the Template folder","text":"If you wish to change the location of the template folder, you can do so in 2 ways:
- By adding the
--local flag to the above command (e.g. pymaker template dump --local). This will dump the default template to the current folder, giving you the option to disable the default template if needed. Note that any files in the folder will be overwritten. - By changing to the folder containing your template and running
pymaker template set. This will set the current folder as the template folder and give you the same option to disable the default template.
You can reset the template location back to the default ~/.pymaker/template folder by running the following command:
$ pymaker template reset\n
"},{"location":"template/replace/#choose-to-use-the-default-template-or-not","title":"Choose to use the Default Template or not","text":"Running the dump command will give you the option to disable the default template completely and ONLY use the exported (or custom) template. You can also do this (or revert back to the default template) by running the following command:
$ pymaker template default <enable|disable>\n
enable will enable the default template, and disable will disable it. Please note that any custom templates you have created will be used regardless, and will overwrite the default template (if enabled) if they have the same file name.
"}]}
\ No newline at end of file
+{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Python Project Generation Tool","text":"A fully customizable Python application to bootstrap Poetry-based boilerplate for you to start developing your Python applications quicker! Includes linting and Pytest libraries.
It will create a new directory for your project (or use the current directory), initialise a git repository, create a virtual environment, and install some basic dependencies for Testing, Linting and more. Optionally, it can also create a GitHub repository for you and push the initial commit.
Latest Version : v0.10.2
"},{"location":"#testing","title":"Testing","text":"The generated project includes pytest and some related plugins to allow you to set up testing straight away.
Write your tests in the tests directory and run them with pytest.
"},{"location":"#linting","title":"Linting","text":"The generated project includes Ruff for linting and code style formatting. Mypy is installed for type checking. These are set quite strictly by default, but you can edit the tools configuration in the pyproject.toml file.
"},{"location":"#customize-the-generated-project","title":"Customize the generated project","text":"You can add extra or edited files to the generated project by adding them to the ~/.pymaker/template directory. The files in this directory will be copied into the generated project, overwriting any existing files with the same name.
It is also possible to dump the whole template into this folder or the current folder so full customization and even removal of files is possible.
"},{"location":"#pre-commit","title":"Pre-commit","text":"The generated project uses pre-commit to run some checks on the code before it is committed. This is a great tool to help keep your code clean.
To install pre-commit, run the following command from inside your venv:
$ pre-commit install\npre-commit installed at .git/hooks/pre-commit\n
"},{"location":"#github-actions-and-configuration","title":"GitHub Actions and Configuration","text":"By default the generated project includes a GitHub Actions workflow to run Dependabot to keep your dependencies up to date. There are also standard templates for Pull Request and Issues.
The plan is to add more workflows in the future, for example running tests and more.
"},{"location":"#changelog-generator","title":"Changelog Generator","text":"Once you have at least one GitHub release, you can generate a CHANGELOG.md file automatically from this, using the included github-changelog-md tool.
You can run this manually by running the following command from inside your virtual environment:
$ poe changelog\n
You need to have a GitHub Personal Access Token set in the config file, see the instructions here for more information.
"},{"location":"#community-related-files","title":"Community related files","text":"To aid in community building, the generated project includes a CODE_OF_CONDUCT.md file. This is based on the Contributor Covenant standard.
Future releases will include other Community related files (for example an AUTHORS file). There are also blank CONTRIBUTING.md and CHANGELOG.md files. The CHANGELOG.md file can be auto-generated.
"},{"location":"#contributing-to-this-project","title":"Contributing to this Project","text":"For information on how to contribute to the project, see the CONTRIBUTING.md file in the root of the repository or on this website
"},{"location":"changelog/","title":"Changelog","text":""},{"location":"changelog/#changelog","title":"Changelog","text":"This is an auto-generated log of all the changes that have been made to the project since the first release.
This project adheres to Semantic Versioning.
"},{"location":"changelog/#v0102-march-13-2024","title":"v0.10.2 (March 13, 2024)","text":"Closed Issues
- License name is missing in the generated README (#321) by seapagan
- The templates for some generated files need updating (#320) by seapagan
New Features
- Add pytest watcher task (#326) by seapagan
Bug Fixes
- Fix some bugs in the template files and update obsolete information (#325) by seapagan
- Fix missing license name in generated README (#324) by seapagan
Dependency Updates
- Build(deps): bump pydantic from 2.6.3 to 2.6.4 (#323) by dependabot[bot]
Full Changelog | Diff | Patch
"},{"location":"changelog/#v0101-march-12-2024","title":"v0.10.1 (March 12, 2024)","text":"Closed Issues
- Empty string for 'homepage' in
pyproject.html crashes Poetry (#317) by seapagan
Testing
- Add unit tests for the
Settings module (#310) by seapagan
Bug Fixes
- Fix bug where bad homepage field crashes
poetry install (#318) by seapagan
Refactoring
- Convert settings module to use new
get_settings() method (#309) by seapagan
Documentation
- Update Docs to mention previous linting changes (#305) by seapagan
Dependency Updates
- Build(deps): bump simple-toml-settings from 0.5.0 to 0.6.0 (#316) by dependabot[bot]
- Build(deps-dev): bump mypy from 1.8.0 to 1.9.0 (#315) by dependabot[bot]
- Build(deps-dev): bump types-requests from 2.31.0.20240218 to 2.31.0.20240311 (#314) by dependabot[bot]
- Build(deps-dev): bump pytest from 8.1.0 to 8.1.1 (#313) by dependabot[bot]
- Build(deps-dev): bump faker from 24.0.0 to 24.1.0 (#312) by dependabot[bot]
- Build(deps-dev): bump ruff from 0.3.1 to 0.3.2 (#311) by dependabot[bot]
- Build(deps): bump simple-toml-settings from 0.4.0 to 0.5.0 (#307) by dependabot[bot]
- Build(deps-dev): bump ruff from 0.3.0 to 0.3.1 (#306) by dependabot[bot]
Full Changelog | Diff | Patch
"},{"location":"changelog/#v0100-march-06-2024","title":"v0.10.0 (March 06, 2024)","text":"Closed Issues
- When missing the config file, it does not properly read the users Git username/email (#291) by seapagan
Bug Fixes
- Fix bug in post create-file hook (#300) by seapagan
Dependency Updates
- Build(deps-dev): bump mkdocs-material from 9.5.12 to 9.5.13 (#303) by dependabot[bot]
- Build(deps-dev): bump pymdown-extensions from 10.7 to 10.7.1 (#302) by dependabot[bot]
- Build(deps-dev): bump faker from 23.3.0 to 24.0.0 (#301) by dependabot[bot]
Full Changelog | Diff | Patch
"},{"location":"changelog/#v095-march-04-2024","title":"v0.9.5 (March 04, 2024)","text":"Closed Issues
- For standalone app, the suggested GitHub URL is wrong, it should be the same as if the app was a package (#296) by seapagan
- Template deps need updating and template config files need a freshening (#294) by seapagan
- Standalone app should have the ending text changed. (#293) by seapagan
- If creating a standalone,
poetry install should set 'package-mode=false' in the pyproject.toml (#292) by seapagan
Merged Pull Requests
- Fix formatting to new Ruff 3.0 (#289) by seapagan
New Features
- Update deps and template, freshen the template config files. (#297) by seapagan
Testing
- Continue writing tests. (#267) by seapagan
- Add a testing stage to CI with coverage reports from codacy (#266) by seapagan
Bug Fixes
- Ask for repo name and offer to create for both type of projects (#298) by seapagan
- Fix several issues with generating standalone projects (#295) by seapagan
Dependency Updates
- Build(deps-dev): bump pytest from 8.0.2 to 8.1.0 (#290) by dependabot[bot]
- Build(deps-dev): bump ruff from 0.2.1 to 0.3.0 (#288) by dependabot[bot]
- Build(deps-dev): bump mkdocs-autorefs from 0.5.0 to 1.0.1 (#287) by dependabot[bot]
- Build(deps-dev): bump mkdocs-material from 9.5.9 to 9.5.12 (#286) by dependabot[bot]
- Build(deps): bump rich from 13.7.0 to 13.7.1 (#285) by dependabot[bot]
- Build(deps): bump pydantic from 2.6.1 to 2.6.3 (#284) by dependabot[bot]
- Build(deps-dev): bump faker from 23.2.0 to 23.3.0 (#282) by dependabot[bot]
- Build(deps-dev): bump mkdocstrings from 0.24.0 to 0.24.1 (#281) by dependabot[bot]
- Build(deps-dev): bump pytest from 8.0.0 to 8.0.2 (#280) by dependabot[bot]
- Build(deps-dev): bump poethepoet from 0.24.4 to 0.25.0 (#277) by dependabot[bot]
- and 35 more dependency updates
Full Changelog | Diff | Patch
"},{"location":"changelog/#v094-december-11-2023","title":"v0.9.4 (December 11, 2023)","text":"This is a security release that fixes a vulnerability in the 'cryptography' package.
Refactoring
- Update pre commit config to use poetry-export-plugin directly (#203) by seapagan
Dependency Updates
- Build(deps-dev): bump mkdocs-material from 9.4.8 to 9.5.1 (#216) by dependabot[bot]
- Build(deps): bump actions/stale from 8 to 9 (#215) by dependabot[bot]
- Build(deps-dev): bump ruff from 0.1.5 to 0.1.7 (#214) by dependabot[bot]
- Build(deps): bump cryptography from 41.0.5 to 41.0.6 (#213) by dependabot[bot]
- Build(deps-dev): bump pytest-xdist from 3.4.0 to 3.5.0 (#209) by dependabot[bot]
- Build(deps-dev): bump pygments from 2.16.1 to 2.17.2 (#208) by dependabot[bot]
- Build(deps-dev): bump faker from 20.0.3 to 20.1.0 (#206) by dependabot[bot]
- Build(deps): bump rich from 13.6.0 to 13.7.0 (#202) by dependabot[bot]
- Build(deps-dev): bump mkdocstrings from 0.23.0 to 0.24.0 (#201) by dependabot[bot]
- Build(deps-dev): bump poethepoet from 0.24.3 to 0.24.4 (#200) by dependabot[bot]
- and 16 more dependency updates
Full Changelog | Diff | Patch
"},{"location":"changelog/#v093-october-29-2023","title":"v0.9.3 (October 29, 2023)","text":"Refactoring
- Run Ruff on github actions (#174) by seapagan
- Migrate linting and formatting to Ruff (#173) by seapagan
Dependency Updates
- Build(deps-dev): bump faker from 19.10.0 to 19.12.0 (#172) by dependabot[bot]
- Build(deps-dev): bump black from 23.10.0 to 23.10.1 (#171) by dependabot[bot]
- Build(deps-dev): bump pylint from 3.0.1 to 3.0.2 (#170) by dependabot[bot]
- Build(deps-dev): bump mypy from 1.6.0 to 1.6.1 (#168) by dependabot[bot]
- Build(deps-dev): bump pylint-pytest from 1.1.2 to 1.1.3 (#167) by dependabot[bot]
Full Changelog | Diff | Patch
"},{"location":"changelog/#v092-october-24-2023","title":"v0.9.2 (October 24, 2023)","text":"Merged Pull Requests
- Migrate to new changelog generator (#165) by seapagan
Dependency Updates
- Build(deps): bump simple-toml-settings from 0.2.2 to 0.3.0 (#163) by dependabot[bot]
- Build(deps-dev): bump pymdown-extensions from 10.3 to 10.3.1 (#162) by dependabot[bot]
- Build(deps-dev): bump pytest-mock from 3.11.1 to 3.12.0 (#161) by dependabot[bot]
- Build(deps-dev): bump black from 23.9.1 to 23.10.0 (#160) by dependabot[bot]
- Build(deps): bump gitpython from 3.1.37 to 3.1.40 (#159) by dependabot[bot]
- Build(deps-dev): bump types-requests from 2.31.0.8 to 2.31.0.10 (#158) by dependabot[bot]
- Build(deps-dev): bump flake8-type-checking from 2.4.2 to 2.5.1 (#157) by dependabot[bot]
- Build(deps): bump urllib3 from 2.0.6 to 2.0.7 (#156) by dependabot[bot]
- Build(deps-dev): bump mkdocs-material from 9.4.5 to 9.4.6 (#154) by dependabot[bot]
- Build(deps-dev): bump mkdocs-git-revision-date-localized-plugin from 1.2.0 to 1.2.1 (#152) by dependabot[bot]
- and 1 more dependency updates
Full Changelog | Diff | Patch
"},{"location":"changelog/#v091-october-12-2023","title":"v0.9.1 (October 12, 2023)","text":"Bug Fixes
- Remove extra '__init__.py' file (#150) by seapagan
Dependency Updates
- Build(deps-dev): bump faker from 19.8.0 to 19.10.0 (#149) by dependabot[bot]
- Build(deps-dev): bump mypy from 1.5.1 to 1.6.0 (#147) by dependabot[bot]
Full Changelog | Diff | Patch
"},{"location":"changelog/#v090-october-10-2023","title":"v0.9.0 (October 10, 2023)","text":"Merged Pull Requests
- Unlock 'poethepoet' upgrades (#142) by seapagan
New Features
- Migrate settings to my 'simple-toml-settings' library (#146) by seapagan
Dependency Updates
- Build(deps-dev): bump mkdocs-material from 9.4.4 to 9.4.5 (#145) by dependabot[bot]
- Build(deps-dev): bump pylint from 2.17.7 to 3.0.1 (#144) by dependabot[bot]
- Build(deps-dev): bump faker from 19.6.2 to 19.8.0 (#143) by dependabot[bot]
- Build(deps-dev): bump pylint-pydantic from 0.2.4 to 0.3.0 (#139) by dependabot[bot]
- Build(deps-dev): bump mkdocs-material from 9.4.3 to 9.4.4 (#138) by dependabot[bot]
- Build(deps-dev): bump flake8-type-checking from 2.4.1 to 2.4.2 (#137) by dependabot[bot]
- Build(deps-dev): bump types-requests from 2.31.0.7 to 2.31.0.8 (#136) by dependabot[bot]
Full Changelog | Diff | Patch
"},{"location":"changelog/#v080-october-04-2023","title":"v0.8.0 (October 04, 2023)","text":"Merged Pull Requests
- Add help to poe tasks (#130) by seapagan
New Features
- Automatically create a GitHub repository for the new project (#134) by seapagan
Refactoring
- Migrate tomli lib to rtoml (#131) by seapagan
Dependency Updates
- Build(deps-dev): bump mkdocs-material from 9.4.2 to 9.4.3 (#133) by dependabot[bot]
- Build(deps): bump urllib3 from 2.0.4 to 2.0.6 (#132) by dependabot[bot]
- Build(deps): bump rich from 13.5.3 to 13.6.0 (#128) by dependabot[bot]
- Build(deps-dev): bump pylint from 2.17.6 to 2.17.7 (#127) by dependabot[bot]
- Build(deps-dev): bump types-requests from 2.31.0.6 to 2.31.0.7 (#126) by dependabot[bot]
- Build(deps-dev): bump poethepoet from 0.23.0 to 0.24.0 (#125) by dependabot[bot]
Full Changelog | Diff | Patch
"},{"location":"changelog/#v070-october-01-2023","title":"v0.7.0 (October 01, 2023)","text":"Merged Pull Requests
- Improve typing across the package (#115) by seapagan
- Adjust suggested git repo name (#103) by seapagan
New Features
- Implement 'config edit' command (#124) by seapagan
- Add '--bare' option (#123) by seapagan
- Add '--standalone' CLI flag (#113) by seapagan
- Add optional github_token setting (#106) by seapagan
- Store and use GitHub username (#104) by seapagan
Documentation
- Adjust and clarify some docs (#114) by seapagan
- Add a contributing guide (#109) by seapagan
- Add a POE Task to automatically create and update the CHANGELOG.md (#107) by seapagan
- Add MkDocs Tasks to the Documentation (#105) by seapagan
Dependency Updates
- Build(deps): bump pydantic from 2.3.0 to 2.4.2 (#122) by dependabot[bot]
- Build(deps-dev): bump types-requests from 2.31.0.4 to 2.31.0.6 (#120) by dependabot[bot]
- Build(deps-dev): bump pylint from 2.17.5 to 2.17.6 (#119) by dependabot[bot]
- Build(deps-dev): bump types-requests from 2.31.0.3 to 2.31.0.4 (#112) by dependabot[bot]
- Build(deps-dev): bump mkdocs-material from 9.4.0 to 9.4.2 (#111) by dependabot[bot]
- Build(deps-dev): bump poethepoet from 0.22.1 to 0.23.0 (#110) by dependabot[bot]
Full Changelog | Diff | Patch
"},{"location":"changelog/#v062-september-24-2023","title":"v0.6.2 (September 24, 2023)","text":"Closed Issues
- --version flag does not work. (#101) by seapagan
Merged Pull Requests
- Add poe tasks for documentation if mkdocs enabled (#100) by seapagan
Bug Fixes
- Fix #101 (--version flag does not work) (#102) by seapagan
Full Changelog | Diff | Patch
"},{"location":"changelog/#v061-september-23-2023","title":"v0.6.1 (September 23, 2023)","text":"Merged Pull Requests
- Update tool versions in both pre-commit configs (#99) by seapagan
Bug Fixes
- Fix typos and wording in the generated readme (#98) by seapagan
Documentation
- Remove dependency spam from changelog (#97) by seapagan
Dependency Updates
- Build(deps): bump gitpython from 3.1.36 to 3.1.37 (#96) by dependabot[bot]
- Build(deps-dev): bump mkdocs-material from 9.3.2 to 9.4.0 (#95) by dependabot[bot]
- Build(deps-dev): bump types-requests from 2.31.0.2 to 2.31.0.3 (#94) by dependabot[bot]
- Build(deps-dev): bump faker from 19.6.1 to 19.6.2 (#93) by dependabot[bot]
- Build(deps-dev): bump mkdocs from 1.5.2 to 1.5.3 (#92) by dependabot[bot]
- Build(deps-dev): bump mkdocs-material from 9.3.1 to 9.3.2 (#91) by dependabot[bot]
- Build(deps): bump rich from 13.5.2 to 13.5.3 (#90) by dependabot[bot]
Full Changelog | Diff | Patch
"},{"location":"changelog/#v060-september-14-2023","title":"v0.6.0 (September 14, 2023)","text":"New Features
- Auto install and update 'pre commit' (#88) by seapagan
- Add code of conduct to project and the template (#87) by seapagan
- Add Github templates to the default output template (#86) by seapagan
Dependency Updates
- Build(deps): bump actions/stale from 5 to 8 (#89) by dependabot[bot]
Full Changelog | Diff | Patch
"},{"location":"changelog/#v051-september-12-2023","title":"v0.5.1 (September 12, 2023)","text":"New Features
- Add --version command to CLI (#63) by seapagan
Bug Fixes
- Add missing 'requests' library to pyproject.toml (#82) by seapagan
Dependency Updates
- Bump faker from 19.6.0 to 19.6.1 (#85) by dependabot[bot]
- Bump gitpython from 3.1.35 to 3.1.36 (#84) by dependabot[bot]
- Bump mkdocs-material from 9.2.8 to 9.3.1 (#83) by dependabot[bot]
- Bump pymarkdownlnt from 0.9.13.3 to 0.9.13.4 (#80) by dependabot[bot]
- Bump faker from 19.3.1 to 19.6.0 (#79) by dependabot[bot]
- Bump black from 23.7.0 to 23.9.1 (#78) by dependabot[bot]
- Bump pytest from 7.4.0 to 7.4.2 (#77) by dependabot[bot]
- Bump gitpython from 3.1.33 to 3.1.35 (#76) by dependabot[bot]
- Bump pymarkdownlnt from 0.9.13 to 0.9.13.3 (#74) by dependabot[bot]
- Bump mkdocs-material from 9.2.7 to 9.2.8 (#73) by dependabot[bot]
- and 8 more dependency updates
Full Changelog | Diff | Patch
"},{"location":"changelog/#v050-august-31-2023","title":"v0.5.0 (August 31, 2023)","text":"New Features
- Ask for homepage & repository if not standalone (#61) by seapagan
- Update template toml and pre-commit deps (#58) by seapagan
- Override config options from command line (#55) by seapagan
- Check PyPI for existing packages (#46) by seapagan
Bug Fixes
- Fix unable to create standalone app (#60) by seapagan
Refactoring
- Override config options from command line (#55) by seapagan
Documentation
- Update docs for latest additions (#59) by seapagan
Dependency Updates
- Bump mkdocs-material from 9.2.3 to 9.2.6 (#57) by dependabot[bot]
- Bump pymdown-extensions from 10.1 to 10.2.1 (#56) by dependabot[bot]
- Bump pymdown-extensions from 10.1 to 10.2 (#54) by dependabot[bot]
- Bump mkdocs-material from 9.2.3 to 9.2.5 (#53) by dependabot[bot]
- Bump pydantic from 2.1.1 to 2.3.0 (#52) by dependabot[bot]
- Bump faker from 19.3.0 to 19.3.1 (#51) by dependabot[bot]
- Bump mkdocs-material from 9.1.21 to 9.2.3 (#50) by dependabot[bot]
- Bump mypy from 1.5.0 to 1.5.1 (#45) by dependabot[bot]
Full Changelog | Diff | Patch
"},{"location":"changelog/#v045-august-17-2023","title":"v0.4.5 (August 17, 2023)","text":"New Features
- Work on the TODO list. See commits for details (#44) by seapagan
Dependency Updates
- Bump pytest-randomly from 3.14.0 to 3.15.0 (#43) by dependabot[bot]
Full Changelog | Diff | Patch
"},{"location":"changelog/#v044-august-15-2023","title":"v0.4.4 (August 15, 2023)","text":"New Features
- Add mkdocs as an option (#42) by seapagan
Dependency Updates
- Bump poethepoet from 0.21.1 to 0.22.0 (#41) by dependabot[bot]
- Bump pytest-randomly from 3.13.0 to 3.14.0 (#40) by dependabot[bot]
Full Changelog | Diff | Patch
"},{"location":"changelog/#v043-august-13-2023","title":"v0.4.3 (August 13, 2023)","text":"New Features
- Tweak linting (#39) by seapagan
Dependency Updates
- Bump mypy from 1.4.1 to 1.5.0 (#38) by dependabot[bot]
Full Changelog | Diff | Patch
"},{"location":"changelog/#v042-august-10-2023","title":"v0.4.2 (August 10, 2023)","text":" - Added a missing runtime dep (rtoml). It must have been in my venv but not in the
pyproject.toml \ud83d\ude44
Full Changelog | Diff | Patch
"},{"location":"changelog/#v041-august-10-2023","title":"v0.4.1 (August 10, 2023)","text":" - Fixed bug where the first-time config file gets the wrong default template path.
- Update the internal template
pyproject.toml and .pre-commit-config.yaml to use latest dependencies
Full Changelog | Diff | Patch
"},{"location":"changelog/#v040-august-10-2023","title":"v0.4.0 (August 10, 2023)","text":"New Features
- Implement custom template additions (#31) by seapagan
Refactoring
- Implement custom template additions (#31) by seapagan
Dependency Updates
- Bump faker from 19.2.0 to 19.3.0 (#37) by dependabot[bot]
- Bump pygments from 2.15.1 to 2.16.1 (#36) by dependabot[bot]
- Bump mkdocs from 1.5.1 to 1.5.2 (#35) by dependabot[bot]
- Bump rich from 13.5.0 to 13.5.2 (#34) by dependabot[bot]
- Bump mkdocs-minify-plugin from 0.7.0 to 0.7.1 (#33) by dependabot[bot]
Full Changelog | Diff | Patch
"},{"location":"changelog/#v030-july-30-2023","title":"v0.3.0 (July 30, 2023)","text":"New Features
- Add a configuration file (#30) by seapagan
- Use conditional logic in templates (#24) by seapagan
Refactoring
- Use conditional logic in templates (#24) by seapagan
Dependency Updates
- Bump mkdocs-material from 9.1.19 to 9.1.21 (#29) by dependabot[bot]
- Bump mkdocs from 1.4.3 to 1.5.1 (#28) by dependabot[bot]
- Bump pylint from 2.17.4 to 2.17.5 (#26) by dependabot[bot]
- Bump pydantic from 2.0.3 to 2.1.1 (#22) by dependabot[bot]
Full Changelog | Diff | Patch
"},{"location":"changelog/#v021-july-26-2023","title":"v0.2.1 (July 26, 2023)","text":"New Features
- Add a documentation site (#23) by seapagan
Documentation
- Add a documentation site (#23) by seapagan
Full Changelog | Diff | Patch
"},{"location":"changelog/#v020-july-26-2023","title":"v0.2.0 (July 26, 2023)","text":"Refactoring
- Move licenses out of template folder (#21) by seapagan
- Subclass the Rich prompt locally (#20) by seapagan
Dependency Updates
- Bump pytest-asyncio from 0.21.0 to 0.21.1 (#19) by dependabot[bot]
- Bump flake8-type-checking from 2.4.0 to 2.4.1 (#18) by dependabot[bot]
- Bump gitpython from 3.1.31 to 3.1.32 (#17) by dependabot[bot]
- Bump pydantic from 2.0.2 to 2.0.3 (#16) by dependabot[bot]
- Bump mock from 5.0.2 to 5.1.0 (#15) by dependabot[bot]
- Bump faker from 18.11.2 to 19.2.0 (#14) by dependabot[bot]
- Bump poethepoet from 0.20.0 to 0.21.1 (#12) by dependabot[bot]
- Bump pytest-reverse from 1.6.0 to 1.7.0 (#10) by dependabot[bot]
- Bump black from 23.3.0 to 23.7.0 (#9) by dependabot[bot]
- Bump pytest-randomly from 3.12.0 to 3.13.0 (#8) by dependabot[bot]
- and 1 more dependency updates
Full Changelog | Diff | Patch
"},{"location":"changelog/#v010-july-06-2023","title":"v0.1.0 (July 06, 2023)","text":"Merged Pull Requests
- Add base app functionality (#1) by seapagan
New Features
- Customize or remove the Package layout (#5) by seapagan
Refactoring
- Refactor the src template layout and logic (#2) by seapagan
This changelog was generated using github-changelog-md by Seapagan
"},{"location":"configuration/","title":"Configuration","text":""},{"location":"configuration/#configuration-file","title":"Configuration file","text":"This app needs minimal configuration, most options default to True. The configuration is stored in a TOML file in a sub-folder of the user's home directory. By default (and currently the only option) this file is stored in ~/.pymaker/config.toml. An example of this file is:
[pymaker]\nauthor_email = \"user@server.com\"\nauthor_name = \"Python User\"\ndefault_license = \"MIT\"\ngithub_username = \"githubuser\" # optional\ngithub_token = \"ghp_1234567890abcdefghij\" # optional\ngithub_protocol = \"ssh\"\ninclude_linters = true\ninclude_mkdocs = true\ninclude_testing = true\ninstall_pre_commit = true\nschema_version = \"1.0\" # for internal use, generally don't change this\ntemplate_folder = \"/home/user/.pymaker/template\"\nuse_default_template = true\nuse_git = true\ncreate_remote = true\n
If this file does not exist, it will be created on first run. The app will ask for the values of author_name, author_email, default_license and github_username. For author_name and author_email it will try to use the current global git user name and email if they are set as defaults, though the user can override these.
"},{"location":"configuration/#configuration-options","title":"Configuration options","text":"The following options are available for configuring Py-Maker:
author_email: The email address of the author.author_name: The name of the author.default_license: The default license to use for the project.github_username: The GitHub username of the author [optional].github_token: The GitHub Personal Access Token of the author [optional]. See below for more information.github_protocol: The protocol to use for GitHub, either ssh or https, defaults to ssh which means that the user will need to have set up an SSH key with GitHub and added it to their account. If you wish to use HTTPS, you will be asked for your GitHub password every time you push to the remote repository.include_linters: Whether to include linters in the project, defaults to trueinclude_mkdocs: Whether to include MkDocs in the project, defaults to trueinclude_testing: Whether to include testing in the project, defaults to trueinstall_pre_commit: Whether to install pre-commit hooks, defaults to trueschema_version: The version of the configuration schema. This should not be modified by hand. Currently, and until version 1.0 is released, this is set to \"none\" to indicate that the schema is not yet stable.template_folder: The path to the template folder.use_default_template: Whether to use the default template, defaults to trueuse_git: Whether to use Git for version control, defaults to truecreate_remote: Whether to create a remote repository on GitHub, defaults to true
All of the boolean options are set to true by default. The template_folder is set to the default template folder, which is ~/.pymaker/template. The schema_version is for internal use, and should not be changed by the user.
"},{"location":"configuration/#view-configuration","title":"View configuration","text":"You can list the current configuration with the command:
$ pymaker config show\n
"},{"location":"configuration/#edit-the-configuration-file","title":"Edit the configuration file","text":"You can edit the configuration file with the command:
$ pymaker config edit\n
This will open the configuration file in your default editor. Under linux it will try to use xdg-open to open the file, and if that fails, it will try to use a few different editors until it finds one that works. Under Windows and Mac it will try to use the default editor.
You may also edit the configuration file manually, by default it is stored in ~/.pymaker/config.toml.
"},{"location":"configuration/#set-configuration","title":"Set configuration","text":"The configuration is set the first time you run the app, but you can change these defaults at any time using the command:
$ pymaker config change\n
The latter command will prompt you for the values of Author name, Author Email, Default License and GitHub Username, then update the configuration file.
"},{"location":"configuration/#add-a-github-personal-access-token","title":"Add a GitHub Personal Access Token","text":"This app is able to create a new GitHub repository for you. To do this, it will need a GitHub Personal Access Token. You can create a new token by going to GitHub Personal Access Tokens and clicking on the \"Generate new token\" button. Use the 'Classic' token option unless you really need more control. Unless you want to use the token on Private repositories, you should check the public_repo option and leave all the other permissions unchecked (this tool does not yet have the option to create a private repository). Give it a name (for your reference only) and chose an expiry date. You can choose never to expire, but this is not recommended. Once you have created the token, copy it (it will only be shown once, so make sure you copy it now). Then run the command:
$ pymaker config token\n
This will accept the token and store it in the configuration file. You can change the token at any time by running the same command again.
NEVER PUSH THE CONFIG FILE TO A REPOSITORY!!!
This shouldnt ever happen since the file is stored in the user's home directory, but it is worth mentioning. If you didn't choose any extra permissions, then the worst that can happen is that someone can use your token to create a new repository. This token is READ-ONLY, so it can't be used to do anything malicious, but it is still a good idea to keep it secret.
"},{"location":"configuration/#manually-editing-the-configuration-file","title":"Manually editing the configuration file","text":"The configuration file is stored in TOML format, and can be edited manually if you wish. The file is stored in ~/.pymaker/config.toml by default. The configuration file is created on first run, so if you have not run the app yet, you will need to create the file manually.
"},{"location":"contributing/","title":"Contributing","text":""},{"location":"contributing/#contributing-to-py-maker","title":"Contributing to Py-Maker","text":"Thank you for your interest in contributing to Py-Maker! We welcome all contributions, big or small.
If you are not sure where to start, please take a look at the open issues. If you have an idea for a new feature or would like to report a bug, please open a new issue. You can also check the TODO List for ideas.
I also welcome contributions to the documentation. If you find any errors or would like to suggest improvements, please open a new issue or submit a Pull Request.
I you would like to contribute to the code, but find the requirements below a bit daunting, please feel free to open a discussion and I can help you get started, or even pair on a PR.
"},{"location":"contributing/#prerequisites","title":"Prerequisites","text":"Since this is a Python project, you will need to have Python installed on your machine. You can download the latest version of Python from the official website or using your Operating system's package manager. This project requires Python 3.9 or higher.
I'd recommend using pyenv to manage your Python installations, the pyenv-installer works for Linux and Mac OS X. For Windows, you can use the pyenv-win port. See here for installation instructions.
We also use Poetry to manage our dependencies. You should have this installed as well. You can install Poetry by following the instructions on the Poetry website.
"},{"location":"contributing/#getting-started","title":"Getting Started","text":"Before you start contributing, please make sure you have read and understood our Code of Conduct and License.
To get started, follow these steps:
- Fork the repository and clone it to your local machine.
- Install the required dependencies (see next section).
- Create a new branch for your changes:
git checkout -b my-new-feature. - Make your changes and commit them:
git commit -am 'Add some feature'. - Push your changes to your fork:
git push origin my-new-feature. - Create a new pull request.
"},{"location":"contributing/#install-dependencies","title":"Install Dependencies","text":"Run the following command to install the required dependencies:
$ poetry install\n
You then need to activate the virtual environment:
$ poetry shell\n
From here you can start working on the project. If you are using an IDE such as VSCode or PyCharm, you can set the use their Python interpreter setting to use the virtual environment that has just been created.
"},{"location":"contributing/#using-pip","title":"Using Pip","text":"If you prefer to use pip instead of poetry, you can install the dependencies using the auto-generated requirements-dev.txt file:
$ pip install -r requirements-dev.txt\n
However, Poetry is the recommended (and only supported) way of developing this project and is tightly integrated with the code and tools.
"},{"location":"contributing/#linting","title":"Linting","text":"I am quite strict about linting and code formatting and have set up a number of pre-commit hooks and tasks to ensure that the code meets the required standards.
Use the poe ruff, poe format and poe mypy tasks regularly. If you use VSCode, install the Ruff andMyPy extensions and set them to run on save. The included .vscode folder has the settings for this.
"},{"location":"contributing/#install-git-pre-commit-hooks","title":"Install Git Pre-Commit hooks","text":"Please install this if you are intending to contribute to the project. It will check commits locally before they are pushed up to the Repo. The GitHub CI runs the linting checks (and in future probably MyPy as well), and will fail if there are any errors.
$ pre-commit install\npre-commit installed at .git/hooks/pre-commit\n
This will ensure that all code meets the required linting standard before being committed.
"},{"location":"contributing/#run-pre-commit-manually","title":"Run pre-commit manually","text":"You can run these checks manually on all staged files using the below command :
poe pre\n
"},{"location":"contributing/#testing","title":"Testing","text":"We are using pytest for testing.
At the moment the test framework is set up but we only have about 50% coverage. We will be adding more tests as we go along - and most definitely welcome any contributions to this area!
If you add any new features, please add tests for them. This will help us to ensure that the code is working as expected and will prevent any regressions. Currently we are not enforcing this until we have better coverage of the code - however if you break any existing tests, the CI will fail.
There is a task set up to run tests:
$ poe test\n
And run a watcher to automatically re-run the tests when files change:
$ poe test:watch\n
You can also run the tests manually using the following command:
$ pytest\n
The task is set up so we can automatically add other options in the future.
"},{"location":"contributing/#changelog","title":"Changelog","text":"The changelog is automatically generated, using this project, so please do not edit it manually.
For maintainers, there is a POE task that will run this and update the changelog file.
$ poe changelog\n
You would also need to add a GitHub Personal Access Token to a local config file as usual. See the section in the Documentation for information.
However, you should NOT include a change to the CHANGELOG.md file in any Pull Requests. This will be handled by the maintainers when a new release is made. Your GitHub username will be added to the changelog automatically beside your PR.
"},{"location":"contributing/#convenience-tasks","title":"Convenience Tasks","text":"There are a few other convenience tasks that can be run using the poe command. These are defined in the pyproject.toml file.
Each of these tasks can have extra options added which will be passed to the underlying tool.
Run mypy on the code base in strict mode:
$ poe mypy\n
Format the code using ruff format:
$ poe format\n
Lint the code using ruff:
$ poe ruff\n
Check the Markdown:
$ poe markdown\n
Run ruff, mypy and format at the same time:
$ poe lint\n
"},{"location":"contributing/#documentation-tasks","title":"Documentation Tasks","text":"These are to help with developing and updating the documentation.
poe docs:serve - Serve the MkDocs locally for testing and developmentpoe docs:serve:all - Same as above, but opens to all interfaces so you can view it on other devices on your networkpoe docs:build - Build the MkDocs site into the dist folderpoe docs:publish - Publish the docs to your GitHub pages. Note that only those with write-access to this repo can do this.
"},{"location":"contributing/#guidelines","title":"Guidelines","text":"Here are some guidelines to follow when contributing to github-changelog-md:
- Follow the PEP 8 style guide. The pre-commit hooks will check for this. We are using the Ruff Formatter.
- Fix any linting errors or warnings. The pre-commit hooks will check for this also. Ruff is installed and set to pretty strict settings. Ruff now replaces all the original linters that were installed. There is also a Markdown linter.
- MyPy is installed and we are using type hints. Please try to add type hints to your code. If you see any areas of the code that are missing type hints, please feel free to open a PR and add them \ud83d\ude01!
- Write clear and concise commit messages.
- Write tests for your code.
- Make sure your code passes all existing and new tests before submitting a pull request.
- Document your code using docstrings. This project uses the Google Docstring Spec though at this time is a bit slack on listing the Args and Returns. I will be adding these in as I go along so feel free to add them in if you are contributing .
- If you add or change any functionality, please update the documentation accordingly.
- Use GitHub issues to report bugs or suggest new features.
If you are using VSCode, there is a config file in the .vscode folder that will help you to follow these guidelines. You may need to install some extensions to get the most out of it. I'll add a list of recommended extensions here soon. The Python, MyPy and Ruff ones are very helpful (the included .vscode folder helps configure these).
"},{"location":"contributing/#contact","title":"Contact","text":"If you have any questions or need help with contributing, please contact me @seapagan on GitHub. You can also use the GitHub Discussions feature.
Happy contributing!
"},{"location":"future-plans/","title":"Future Plans","text":""},{"location":"future-plans/#future-plans","title":"Future Plans","text":"The below is a list of things I'd like to add to the project in the future, and is kinda a 'work list' for me.
Everything below will be implemented and are in no particular order or importance.
"},{"location":"future-plans/#general","title":"General","text":" - Add a flag to overwrite existing files if the directory exists. Make this require confirmation. Alternately allow overwrite with confirmation if an existing/populated directory is found. Add a force flag to skip confirmation.
I think DO NOT allow this when '.' is specified as this could be disastrous. - Add cmd line options to specify the project name, author, etc. so the user doesn't have to enter them manually.
Not sure if this is needed once we add the CLI parameters to the config file. May be useful for automation though. - Add a command to the CLI template command to show the template files as a tree, marking whether each file/folder is from the internal templates or the user's templates.
- Implement a 'plugin' functionality where we can specify modified/extra files to be added to the generated project. This would also add a command line flag (ie
--django, --pydantic or --fastapi or whatever) to use that plugin, and a config setting to specify using this plugin always. Plugins could be built-in (provided with the package) or user-defined (in the users /pymaker/plugins folder or installable via pip). Have a config setting to specify which plugins are enabled. - Include an optional
vscode settings file in the generated project, optimized for python projects. This could include recommended extensions. - Perhaps add AUTHORS.md skeleton.
- Add a default dockerfile? Maybe a docker-compose file as well- Both for this project and for the generated projects?
- Update the
config CLI command to enable setting/flipping individual config settings from the command line. - check for an existing GitHub repository when the user supplies the repo name and ask for an alternative if it exists.
- add option (probably using the eventual plugin functionality) to create a skeleton
typer CLI app. - if it creates a new remote GitHub repo, print the GitHub URL to the console.
- when creating a github repo, set the
About section to the description field in the pyproject.toml file. Also can set the homepage if specified. Options to add tags?
"},{"location":"future-plans/#bugs","title":"Bugs","text":" - the
release_text option does not work if the --next-release is specified and corresponds to that release_text version. - no validation on the URI input fields (hompage, repository) which could cause Pooetry to fail to install the package.
"},{"location":"future-plans/#back-burner","title":"Back Burner","text":"These are ideas that I may or may not implement. They are here for reference.
- Modify boolean settings in the config to have the values 'yes', 'no' or 'ask'? This will be a bit lower priority and not sure if it's worth it.
- Add some form of 'extra packages' command line option and config setting to automatically add extra packages to the generated
pyproject.toml file. - Add template GitHub workflows for CI/CD, testing, etc. CodeQL or is that too much (I do use it in most of my repos)?
- Add the
actions/stale action to the generated project.
"},{"location":"future-plans/#refactoring-code-cleanup","title":"Refactoring / Code Cleanup","text":" - Refactor the
PyMaker class as its getting a bit messy. Maybe split it into multiple classes with specific responsibilities. - Sort out the nested
if/else statements in PyMaker.get_sanitized_package_name. - split the file copy and template handling functionality into it's own module and have the
PyMaker class use it. - split the
ExitErrors class into an 'errors' module, add more error types if needed and use them throughout the code.
"},{"location":"future-plans/#documentation","title":"Documentation","text":" - Add usage examples and perhaps a walk-through to the documentation. Maybe with a YouTube video?
- explain how to add more License templates to the 'licenses' module
"},{"location":"future-plans/#testing","title":"Testing","text":" - Add testing with Pytest (
IN PROGRESS)
"},{"location":"installation/","title":"Installation","text":"It is best to install this package globally, rather than in a virtual environment, as it is intended to be used to create new projects. Since we are using Poetry to manage the dependencies, a virtual environment will be created for you anyway specific to each project you are creating.
"},{"location":"installation/#release-version","title":"Release Version","text":"Install the package globally using pip:
$ pip install pyproject-maker\n
If you cannot install globally due to permissions, you can install it to your user install directory:
$ pip install --user pyproject-maker\n
or use pipx (recommended method)
$ pipx install pyproject-maker\n
"},{"location":"installation/#bleeding-edge-version","title":"Bleeding Edge Version","text":"It is possible to install the latest development version of the package directly from the repository. In most cases this should be safe to do, but it is possible that the development version may not be stable or have bugs. If you are having issues with the development version, please open an issue on the repository.
Use pipx (recommended method):
$ pipx install git+https://github.com/seapagan/py-maker\n
Using pip:
$ pip install git+https://github.com/seapagan/py-maker\n
You can also use the --user flag for pip if you do not have permissions to install globally. This is NOT needed for pipx.
Lastly, you can clone the repository and install from the local copy:
$ git clone https://github.com/seapagan/py-maker\n$ cd py-maker\n$ pip install .\n
"},{"location":"license/","title":"License","text":"MIT License
Copyright (c) 2023 Grant Ramsay
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
"},{"location":"tasks/","title":"Task Runner","text":"The task-runner Poe the Poet is installed in the new project as a development dependency which allows us to run simple tasks (similar to npm or yarn scripts).
These are run (from within the virtual environment) using the poe command and then the script name, for example:
$ poe pre\n
To get a list of all available tasks with a description, run:
$ poe\n
You can define your own, but there are currently several specific ones provided in the new project:
pre : Run pre-commit run --all-filesruff: Run Ruff linter on all Python files in the project.format: Run Ruff Formatter on all Python files in the project.mypy : Run MyPy type-checker on all Python files in the project.-
markdown : Run pymarkdown on all markdown files in the project.
-
lint = Runs ruff, formatter, mypy, markdown in sequence
If you selected to install MkDocs with this project, then there are some extra tasks to help with that:
docs:publish : Deploy the documentation to GitHub pages.docs:build : Build the documentation locally.docs:serve : Serve the documentation locally. Useful during development.docs:serve:all : As above, but allows access from other devices on the network.
There is also a task to run the tests if they were selected:
$ poe test\n
And run a watcher to automatically re-run the tests when files change:
$ poe test:watch\n
Finally, you can automatically generate your CHANGELOG.md file using:
$ poe changelog\n
The changelog uses my Markdown Changelog Generator tool to generate the changelog, check the documentation for that tool for more information.
These tasks are all defined in the pyproject.toml file in the [tool.poe.tasks] section. Take a look at this file if you want to add or remove tasks.
"},{"location":"usage/","title":"Using PyMaker","text":""},{"location":"usage/#create-a-new-project","title":"Create a new project","text":"To create a new project, run the following command:
$ pymaker new <project-folder>\n
This will create a new directory with the name you provide.
You can create a new project in the current directory by using . as the project folder name. This must be an empty directory:
$ mkdir test-project\n$ cd test-project\n$ pymaker new .\n
The App will then run the steps needed to get you started quickly:
- Copy the template files into the new directory
- Initialise a git repository
- Commit the boilerplate to Git
You will be asked a series of questions to customise the new project.
"},{"location":"usage/#choose-a-package-name-and-description","title":"Choose a package name and description","text":"When it asks \"Package Name?\" you can choose two variants :
- If you are creating a standard Python package that can optionally be uploaded to PyPI, enter a package name here. Note that underscores (\"_\") must be used as opposed to dashes (\"-\") to comply with Python package naming rules. Default is the project folder name with underscores replacing dashes, spaces or dots.
- For a stand-alone tool that will not be uploaded to PyPI, or is not a library, enter '-' for the package name. In this case the
main.py will just be placed in the project root and no package folder will be created or referenced. You can also specify --standalone on the command line to skip this question.
For option 1 above, the App will check if the package name is available on PyPI or if it has already been used. In the latter case, you will be asked to choose another name.
"},{"location":"usage/#command-line-options","title":"Command line options","text":"There are a few command line options that can be used to customise the build. Command line options override any settings in the config file.
For example, if use_git = false is set in the config file, then passing --git on the command line will override this and initialise a Git repository.
"},{"location":"usage/#-y-or-yes","title":"-y or --yes","text":"Accept all defaults and do not ask any questions.
"},{"location":"usage/#-git-no-git","title":"--git / --no-git","text":"Initialise a Git repository. Default is True unless use_git = false is set in the config file or --no-git is passed on the command line.
"},{"location":"usage/#-test-no-test","title":"--test / --no-test","text":"Create a test directory and add the pytest dependency plus a few related plugins to the pyproject.toml file. Default is True unless include_testing = false is set in the config file or --no-test is passed on the command line.
"},{"location":"usage/#-lint-no-lint","title":"--lint / --no-lint","text":"Add linting dependencies and configuration to the pyproject.toml file. Default is True unless include_linters = false is set in the config file or --no-lint is passed on the command line.
"},{"location":"usage/#-docs-no-docs","title":"--docs / --no-docs","text":"Add MkDocs and some plugins to the pyproject.toml file. Default is True unless include_mkdocs = false is set in the config file or --no-docs is passed on the command line.
If you choose to run poetry automatically, this will also add a customized mkdocs.yml file and create a new default MkDocs site in the docs folder. Some useful plugins are also installed and added to the mkdocs.yml file.
"},{"location":"usage/#-github-no-github","title":"--github / --no-github","text":"Create a GitHub repository and push the initial commit. Default is True unless create_remote = false is set in the config file or --no-github is passed on the command line. This option needs a GitHub Personal Access Token to be set in the config file, see here
"},{"location":"usage/#-standalone","title":"--standalone","text":"Generate a stand-alone script instead of a package. This will place the main.py file in the project root and not create a package folder. This is useful for creating a single script that can be run from the command line. this is equivalent to entering - for the package name.
"},{"location":"usage/#-bare","title":"--bare","text":"Generate a project without Testing, linting or documentation libraries and configurations. It will also NOT initialise a Git repository. Currently there is no config file option to do this automatically, you must use the command line option.
"},{"location":"usage/#run-poetry-install-automatically","title":"Run poetry install automatically","text":"You will be asked if you want to run poetry install automatically. This will create a virtual environment and install the dependencies, plus also create a bare MkDocs site and configuration. This is the recommended option.
You will still need to run poetry shell to activate the virtual environment from inside the new project folder.
"},{"location":"usage/#start-developing","title":"Start developing","text":"You should now change into the new directory, install dependencies and activate the virtual environment:
$ cd <project-folder>\n$ poetry install # if not done automatically already\n$ poetry shell\n
Now, you can start developing
"},{"location":"usage/#example-run","title":"Example run","text":"$ pymaker new secret-docs\nPyMaker - Generate a Python project skeleton.\n\nCreating a new project at /home/bathroom/secret-docs\n\nName of the Application? (Secret Docs):\nPackage Name? (Use '-' for standalone script) (secret_docs):\nDescription of the Application?: Store all the Bigly amount of secret documents\nI have in the bathroom\n\nAuthor Name? (): Orange Tango\nAuthor Email? (): bigly@spraytan.org\nApplication License? [None/Apache2/BSD3/BSD2/GPL2/GPL3/LGPL/MIT/MPL2/CDDL/EPL2] (MIT):\n\nCreating a New Python app with the below settings :\n\n Description : Store all the Bigly amount of secret documents I have in the\n bathroom\n Package Name : secret_docs\n Author : Orange Tango\n Email : bigly@straytan.org\n License : MIT\n Project Dir : /home/bathroom/secret-docs\n Name : Secret Docs\n Standalone : False\n\nIs this correct? [y/n] (y):\n\n--> Creating project folder ... Done\n\nShould I Run 'poetry install' now? [y/n] (y):\nCreating virtualenv secret-docs in /home/bathroom/secret-docs/.venv\nUpdating dependencies\nResolving dependencies... (11.6s)\n\nPackage operations: 103 installs, 1 update, 0 removals\n\n \u2022 Installing lazy-object-proxy (1.9.0)\n \u2022 Installing six (1.16.0)\n\n <snippy snip>\n\n \u2022 Installing pytest-xdist (3.3.1)\n \u2022 Installing tryceratops (2.3.2)\n\nWriting lock file\n\nInstalling the current project: secret-docs (0.1.0)\n\n--> Creating MkDocs project\nINFO - Writing config file: ./mkdocs.yml\nINFO - Writing initial docs: ./docs/index.md\n\n--> Creating Git repository ... Done\n\n--> Project created successfully.\n\nNext steps:\n\n1. Change to the project directory:\n2. Install the dependencies if not done above (creates a virtual environment):\n $ poetry install\n3. Activate the virtual environment:\n $ poetry shell\n4. Run the application:\n $ secret-docs\n5. Code!\n\nSee the README.md file for more information.\n
"},{"location":"template/internal/","title":"The Internal Template","text":"By default, the generated application will have a basic template that you can use to get started, this template is stored inside the package itself. It will contain all you need to get started, including a basic README.md file.
The dependency management is handled by Poetry, and we include a pyproject.toml file with several useful dependencies:
- PyTest for testing, along with several useful plugins.
- Ruff for linting and formatting. This replaces the need for
flake8, black, isort and more. The default pyproject.toml contains a quite strict configuration by default, but you can modify it to suit your needs. - MyPy for static type checking.
- pre-commit for running checks before committing code.
The pyproject.toml contains a useable configuration for all of these tools, but you can modify it to suit your needs.
It also contains several tasks for running the tests, linting, formatting and more. These use the Poe The Poet Poetry extension see Task Runner for more information.
"},{"location":"template/modify/","title":"Adding or Modifying files in the template","text":"If you wish to add or change specific files in the template, you can do so by adding them to the ~/.pymaker/template folder. The files (and folders) in this folder will be copied to the root of the project when the template is generated.
Files in this global template folder will override any files in the default template, so you can for example change the README.md file, add to the .gitignore or even add a complete extra folder structure.
If you want to do a major change to the template, you can actually dump the default template to this folder and modify or delete files as you see fit. See the next section for more information on how to do this.
"},{"location":"template/replace/","title":"Replacing the Default Template","text":""},{"location":"template/replace/#dump-the-default-template","title":"Dump the Default Template","text":"Should you wish to heavily modify the default template, or even replace it completely, you can do so by dumping the default template to the ~/.pymaker/template folder. This will copy all files from the default template to the global template folder, where you can modify or delete them as you see fit.
To do this, run the following command:
$ pymaker template dump\n
This will copy the default template to the global template folder (~/.pymaker/template). You can then modify or delete files as you see fit.
Running this command will ask you if you wish to set this exported template as the default template. It will then ask you if you want to disable the internal template. If you answer yes, then the internal template will be disabled, and ONLY the exported template will be used instead. Otherwise, both will still be used with the exported template taking precedence.
"},{"location":"template/replace/#change-the-location-of-the-template-folder","title":"Change the location of the Template folder","text":"If you wish to change the location of the template folder, you can do so in 2 ways:
- By adding the
--local flag to the above command (e.g. pymaker template dump --local). This will dump the default template to the current folder, giving you the option to disable the default template if needed. Note that any files in the folder will be overwritten. - By changing to the folder containing your template and running
pymaker template set. This will set the current folder as the template folder and give you the same option to disable the default template.
You can reset the template location back to the default ~/.pymaker/template folder by running the following command:
$ pymaker template reset\n
"},{"location":"template/replace/#choose-to-use-the-default-template-or-not","title":"Choose to use the Default Template or not","text":"Running the dump command will give you the option to disable the default template completely and ONLY use the exported (or custom) template. You can also do this (or revert back to the default template) by running the following command:
$ pymaker template default <enable|disable>\n
enable will enable the default template, and disable will disable it. Please note that any custom templates you have created will be used regardless, and will overwrite the default template (if enabled) if they have the same file name.
"}]}
\ No newline at end of file
diff --git a/sitemap.xml.gz b/sitemap.xml.gz
index d2e74572..6226a4d4 100644
Binary files a/sitemap.xml.gz and b/sitemap.xml.gz differ
diff --git a/tasks/index.html b/tasks/index.html
index 2905497e..36ff7421 100644
--- a/tasks/index.html
+++ b/tasks/index.html
@@ -1,4 +1,4 @@
-Task Runner - Python Project Generation Tool Task Runner
The task-runner Poe the Poet is installed in the new project as a development dependency which allows us to run simple tasks (similar to npm or yarn scripts).
These are run (from within the virtual environment) using the poe command and then the script name, for example:
$ poe pre
+Task Runner - Pymaker - Easily generate a new Python Project Task Runner
The task-runner Poe the Poet is installed in the new project as a development dependency which allows us to run simple tasks (similar to npm or yarn scripts).
These are run (from within the virtual environment) using the poe command and then the script name, for example:
$ poe pre
To get a list of all available tasks with a description, run:
$ poe
You can define your own, but there are currently several specific ones provided in the new project:
pre : Run pre-commit run --all-filesruff: Run Ruff linter on all Python files in the project.format: Run Ruff Formatter on all Python files in the project.mypy : Run MyPy type-checker on all Python files in the project.markdown : Run pymarkdown on all markdown files in the project.
lint = Runs ruff, formatter, mypy, markdown in sequence
If you selected to install MkDocs with this project, then there are some extra tasks to help with that:
docs:publish : Deploy the documentation to GitHub pages.docs:build : Build the documentation locally.docs:serve : Serve the documentation locally. Useful during development.docs:serve:all : As above, but allows access from other devices on the network.
There is also a task to run the tests if they were selected:
$ poe test
And run a watcher to automatically re-run the tests when files change:
$ poe test:watch
diff --git a/template/internal/index.html b/template/internal/index.html
index 8b6bab71..d63bea50 100644
--- a/template/internal/index.html
+++ b/template/internal/index.html
@@ -1 +1 @@
-Internal Template - Python Project Generation Tool The Internal Template
By default, the generated application will have a basic template that you can use to get started, this template is stored inside the package itself. It will contain all you need to get started, including a basic README.md file.
The dependency management is handled by Poetry, and we include a pyproject.toml file with several useful dependencies:
- PyTest for testing, along with several useful plugins.
- Ruff for linting and formatting. This replaces the need for
flake8, black, isort and more. The default pyproject.toml contains a quite strict configuration by default, but you can modify it to suit your needs. - MyPy for static type checking.
- pre-commit for running checks before committing code.
The pyproject.toml contains a useable configuration for all of these tools, but you can modify it to suit your needs.
It also contains several tasks for running the tests, linting, formatting and more. These use the Poe The Poet Poetry extension see Task Runner for more information.
Internal Template - Pymaker - Easily generate a new Python Project The Internal Template
By default, the generated application will have a basic template that you can use to get started, this template is stored inside the package itself. It will contain all you need to get started, including a basic README.md file.
The dependency management is handled by Poetry, and we include a pyproject.toml file with several useful dependencies:
- PyTest for testing, along with several useful plugins.
- Ruff for linting and formatting. This replaces the need for
flake8, black, isort and more. The default pyproject.toml contains a quite strict configuration by default, but you can modify it to suit your needs. - MyPy for static type checking.
- pre-commit for running checks before committing code.
The pyproject.toml contains a useable configuration for all of these tools, but you can modify it to suit your needs.
It also contains several tasks for running the tests, linting, formatting and more. These use the Poe The Poet Poetry extension see Task Runner for more information.
Modifying - Python Project Generation Tool Adding or Modifying files in the template
If you wish to add or change specific files in the template, you can do so by adding them to the ~/.pymaker/template folder. The files (and folders) in this folder will be copied to the root of the project when the template is generated.
Files in this global template folder will override any files in the default template, so you can for example change the README.md file, add to the .gitignore or even add a complete extra folder structure.
If you want to do a major change to the template, you can actually dump the default template to this folder and modify or delete files as you see fit. See the next section for more information on how to do this.
Modifying - Pymaker - Easily generate a new Python Project Adding or Modifying files in the template
If you wish to add or change specific files in the template, you can do so by adding them to the ~/.pymaker/template folder. The files (and folders) in this folder will be copied to the root of the project when the template is generated.
Files in this global template folder will override any files in the default template, so you can for example change the README.md file, add to the .gitignore or even add a complete extra folder structure.
If you want to do a major change to the template, you can actually dump the default template to this folder and modify or delete files as you see fit. See the next section for more information on how to do this.
Replacing - Python Project Generation Tool Replacing the Default Template
Dump the Default Template
Should you wish to heavily modify the default template, or even replace it completely, you can do so by dumping the default template to the ~/.pymaker/template folder. This will copy all files from the default template to the global template folder, where you can modify or delete them as you see fit.
To do this, run the following command:
$ pymaker template dump
+Replacing - Pymaker - Easily generate a new Python Project Replacing the Default Template
Dump the Default Template
Should you wish to heavily modify the default template, or even replace it completely, you can do so by dumping the default template to the ~/.pymaker/template folder. This will copy all files from the default template to the global template folder, where you can modify or delete them as you see fit.
To do this, run the following command:
$ pymaker template dump
This will copy the default template to the global template folder (~/.pymaker/template). You can then modify or delete files as you see fit.
Running this command will ask you if you wish to set this exported template as the default template. It will then ask you if you want to disable the internal template. If you answer yes, then the internal template will be disabled, and ONLY the exported template will be used instead. Otherwise, both will still be used with the exported template taking precedence.
Change the location of the Template folder
If you wish to change the location of the template folder, you can do so in 2 ways:
- By adding the
--local flag to the above command (e.g. pymaker template dump --local). This will dump the default template to the current folder, giving you the option to disable the default template if needed. Note that any files in the folder will be overwritten. - By changing to the folder containing your template and running
pymaker template set. This will set the current folder as the template folder and give you the same option to disable the default template.
You can reset the template location back to the default ~/.pymaker/template folder by running the following command:
$ pymaker template reset
Choose to use the Default Template or not
Running the dump command will give you the option to disable the default template completely and ONLY use the exported (or custom) template. You can also do this (or revert back to the default template) by running the following command:
$ pymaker template default <enable|disable>
enable will enable the default template, and disable will disable it. Please note that any custom templates you have created will be used regardless, and will overwrite the default template (if enabled) if they have the same file name.
Usage - Python Project Generation Tool Using PyMaker
Create a new project
To create a new project, run the following command:
$ pymaker new <project-folder>
+Usage - Pymaker - Easily generate a new Python Project Using PyMaker
Create a new project
To create a new project, run the following command:
$ pymaker new <project-folder>
This will create a new directory with the name you provide.
You can create a new project in the current directory by using . as the project folder name. This must be an empty directory:
$ mkdir test-project
$ cd test-project
$ pymaker new .