diff --git a/search/search_index.json b/search/search_index.json index 195fed56..8c295149 100644 --- a/search/search_index.json +++ b/search/search_index.json @@ -1 +1 @@ -{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Python Project Generation Tool","text":"

This is a command line tool to help you create new Python projects. It will create a new directory for your project, initialise a git repository, create a virtual environment, and install some basic dependencies.

Latest Version : v0.4.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 flake8 (with several plugins) for linting and Black for formatting. Mypy is installed for type checking. isort, Pylint and tyrceratops are also installed as standard.

"},{"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":"configuration/","title":"Configuration","text":""},{"location":"configuration/#configuration-file","title":"Configuration file","text":"

This app needs minimal configuration, currently just storing defaults for the author_name, author_email and default_license. This is stored in a configuration 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\"\nschema_version = \"1.0\" # for internal use, generally don't change this\ntemplate_folder = \"/home/user/.pymaker/template\"\nuse_default_template = true\n

If this file does not exist, it will be created on first run. The app will ask for the values of these fields. For author_name and author_email it will try to use the current git user name and email if they are set as defaults, though the user can override these.

"},{"location":"configuration/#view-configuration","title":"View configuration","text":"

You can list the current configuration with the command:

$ pymaker config show\n
"},{"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 the fields, and then update the configuration file.

"},{"location":"future-plans/","title":"Future Plans","text":""},{"location":"future-plans/#todo-list","title":"TODO List","text":""},{"location":"future-plans/#general","title":"General","text":""},{"location":"future-plans/#documentation","title":"Documentation","text":""},{"location":"installation/","title":"Installation","text":"

It is probably better 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.

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

$ pipx install pyproject-maker\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":"quick-start/","title":"Quick Start","text":""},{"location":"quick-start/#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:

  1. Copy the template files into the new directory
  2. Initialise a git repository
  3. Commit the boilerplate to Git

You will be asked a series of questions to customise the new project.

"},{"location":"quick-start/#choose-a-package-name-and-description","title":"Choose a package name and description","text":"

When it asks \"Package Name?\" you can choose two variants :

  1. 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.
  2. For a stand-alone tool that will not ne 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.
"},{"location":"quick-start/#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\n$ poetry shell\n

Now, you can start developing

"},{"location":"quick-start/#example-run","title":"Example run","text":"
$ pymaker new test-project\nPyMaker - Generate a Python project skeleton.\n\nCreating a new project at /home/bathroom/test-project\n\nName of the Application? (Test Project):\nPackage Name? (Use '-' for standalone script) (test_project):\nDescription of the Application?: An amazing Bigly test project.\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 : An amazing Bigly test project. better than you've ever seen before!\n   Package Name : test_project\n         Author : Orange Tango\n          Email : bigly@spraytan.org\n        License : MIT\n    Project Dir : /home/bathroom/test-project\n           Name : Test Project\n\nIs this correct? [y/n] (y): y\n\n--> Creating project folder ... Done\n--> Creating Git repository ... Done\n\n--> Project created successfully.\n\nNext steps:\n\n    1) Change to the project directory:\n    2) Install the dependencies (creates a virtual environment):\n        'poetry install'\n    3) Activate the virtual environment:\n        'poetry shell'\n    4) Run the application:\n        'test-project'\n    5) Code!\n\nSee the README.md file for more information.\n
"},{"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 scripts).

These are run (from within the virtual environment) using the poe command and then the script name, for example:

$ poe pre\n

You can define your own, but there are 7 specific ones provided with the script.

These are 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":"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:

"},{"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:

  1. 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.
  2. 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 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 still be used, and will overwrite the default template 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":"

This is a command line tool to help you create new Python projects. It will create a new directory for your project, initialise a git repository, create a virtual environment, and install some basic dependencies.

Latest Version : v0.4.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 flake8 (with several plugins) for linting and Black for formatting. Mypy is installed for type checking. isort, Pylint and tyrceratops are also installed as standard.

"},{"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":"configuration/","title":"Configuration","text":""},{"location":"configuration/#configuration-file","title":"Configuration file","text":"

This app needs minimal configuration, currently just storing defaults for the author_name, author_email and default_license. This is stored in a configuration 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\"\nschema_version = \"1.0\" # for internal use, generally don't change this\ntemplate_folder = \"/home/user/.pymaker/template\"\nuse_default_template = true\n

If this file does not exist, it will be created on first run. The app will ask for the values of these fields. For author_name and author_email it will try to use the current git user name and email if they are set as defaults, though the user can override these.

"},{"location":"configuration/#view-configuration","title":"View configuration","text":"

You can list the current configuration with the command:

$ pymaker config show\n
"},{"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 the fields, and then update the configuration file.

"},{"location":"future-plans/","title":"Future Plans","text":""},{"location":"future-plans/#todo-list","title":"TODO List","text":""},{"location":"future-plans/#general","title":"General","text":""},{"location":"future-plans/#documentation","title":"Documentation","text":""},{"location":"installation/","title":"Installation","text":"

It is probably better 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.

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

$ pipx install pyproject-maker\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":"quick-start/","title":"Quick Start","text":""},{"location":"quick-start/#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:

  1. Copy the template files into the new directory
  2. Initialise a git repository
  3. Commit the boilerplate to Git

You will be asked a series of questions to customise the new project.

"},{"location":"quick-start/#choose-a-package-name-and-description","title":"Choose a package name and description","text":"

When it asks \"Package Name?\" you can choose two variants :

  1. 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.
  2. For a stand-alone tool that will not ne 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.
"},{"location":"quick-start/#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\n$ poetry shell\n

Now, you can start developing

"},{"location":"quick-start/#example-run","title":"Example run","text":"
$ pymaker new test-project\nPyMaker - Generate a Python project skeleton.\n\nCreating a new project at /home/bathroom/test-project\n\nName of the Application? (Test Project):\nPackage Name? (Use '-' for standalone script) (test_project):\nDescription of the Application?: An amazing Bigly test project.\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 : An amazing Bigly test project. better than you've ever seen before!\n   Package Name : test_project\n         Author : Orange Tango\n          Email : bigly@spraytan.org\n        License : MIT\n    Project Dir : /home/bathroom/test-project\n           Name : Test Project\n\nIs this correct? [y/n] (y): y\n\n--> Creating project folder ... Done\n--> Creating Git repository ... Done\n\n--> Project created successfully.\n\nNext steps:\n\n    1) Change to the project directory:\n    2) Install the dependencies (creates a virtual environment):\n        'poetry install'\n    3) Activate the virtual environment:\n        'poetry shell'\n    4) Run the application:\n        'test-project'\n    5) Code!\n\nSee the README.md file for more information.\n
"},{"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 scripts).

These are run (from within the virtual environment) using the poe command and then the script name, for example:

$ poe pre\n

You can define your own, but there are 8 specific ones provided with the script.

These are 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":"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:

"},{"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:

  1. 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.
  2. 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 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 still be used, and will overwrite the default template if they have the same file name.

"}]} \ No newline at end of file diff --git a/sitemap.xml.gz b/sitemap.xml.gz index 93890920..b597da0c 100644 Binary files a/sitemap.xml.gz and b/sitemap.xml.gz differ diff --git a/tasks/index.html b/tasks/index.html index fb477583..93b7e2c9 100644 --- a/tasks/index.html +++ b/tasks/index.html @@ -1,2 +1,2 @@ Task Runner - Python Project Generation Tool
Skip to content

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 scripts).

These are run (from within the virtual environment) using the poe command and then the script name, for example:

$ poe pre
-

You can define your own, but there are 7 specific ones provided with the script.

  • pre : Run pre-commit run --all-files
  • pylint: Run Pylint on all Python files in the project.
  • mypy = Run MyPy type-checker on all Python files in the project.
  • flake8 = Run Flake8 linter on all Python files in the project.
  • black = Run Black code formatter on all Python files in the project.

  • try = Run Tryceratops linter on all Python files in the project.

  • lint = Runs pylint, mypy, flake8 and black in sequence

These are 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.

Last update: July 30, 2023
Created: July 26, 2023
\ No newline at end of file +

You can define your own, but there are 8 specific ones provided with the script.

These are 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.

Last update: August 13, 2023
Created: July 26, 2023
\ No newline at end of file