https://github.com/grok-ai/py-template
Generic template to bootstrap your Python project.
https://github.com/grok-ai/py-template
Last synced: 2 months ago
JSON representation
Generic template to bootstrap your Python project.
- Host: GitHub
- URL: https://github.com/grok-ai/py-template
- Owner: grok-ai
- License: mit
- Created: 2025-02-19T13:42:34.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2025-03-10T22:36:41.000Z (4 months ago)
- Last Synced: 2025-03-28T16:51:18.117Z (3 months ago)
- Language: Python
- Size: 27.3 KB
- Stars: 17
- Watchers: 2
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# py-template
A template to bootstrap Python projects following best practices.
## 🚀 How to Use This Template
You can create a new project in **two ways**:
### 🔹 Automatic Setup (Recommended)
Run:
```bash
curl -fsSL https://raw.githubusercontent.com/grok-ai/py-template/main/setup.sh -o setup.sh && bash setup.sh
```
This will:
- Install [uv](https://github.com/astral-sh/uv) if needed.
- Use [Copier](https://copier.readthedocs.io/en/stable/) to generate the project.
- Prompt for project configuration (see [Customize the Project](#3-customize-the-project)).
- (Optionally) set up the environment (dependencies, virtual environment).
- Initialize Git and optionally push the repository.
### 🔹 Manual Setup
Install [uv](https://github.com/astral-sh/uv) and set up Copier:
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
export PATH="$HOME/.local/bin:$HOME/.cargo/bin:$PATH"
```
Then, create a new project with:
```bash
uvx copier copy --trust gh:grok-ai/py-template
```
Once completed, the project will be initialized in ``.
---
## 3. Customize the Project
During setup, you will be prompted for the following configurations:
- **Project Folder**: Name of the project folder.
- **Python Package Name**: Defaults to the folder name in lowercase with spaces replaced by underscores.
- **Description**: A short description of your project.
- **Maintainers**: A list of maintainers (name & email).
- **Remote Option** (`remote_option`):
- **GitHub**: Push the project to a GitHub repository.
- **Manual**: Provide a custom remote URL (e.g., GitHub, GitLab, Bitbucket).
- **No Remote**: Skip configuring a remote.
- **Push to Remote** (`push_to_remote`): If using GitHub or manual, decide whether to automatically push after initialization.
- **License**: Choose a license (MIT, Apache-2.0).
- **Use Pre-commit Hooks** (`use_precommit`): Enable or disable pre-commit hooks.
- **Dependencies**: Define dependencies to install.
- **Initialize Environment** (`env_init`): Choose whether to set up a virtual environment immediately.
---
## 4. Manual Push to a Remote Repository (Optional)
If `push_to_remote=false` or no remote was set, you can manually add and push later:
```bash
git remote add origin https://github.com/your/repository
git push -u origin main
```
Use the appropriate URL for GitHub, GitLab, or any other Git host.
---
## 5. Development Setup
Once set up, manage dependencies with uv. The virtual environment is stored in `.venv`.
---
## ✨ Features
- **Version Control**: Automatically initializes a Git repository.
- **Optional Remote Push**: Configure a Git remote (GitHub or manual) and optionally push to it.
- **Pre-commit Hooks**: If enabled, sets up [pre-commit hooks](https://pre-commit.com/).
- **Modern Project Structure**: Uses an organized `src/` layout.
- **Flexible**: Simple configuration logic for licensing, dependencies, and environment setup.
- **`PROJECT_ROOT` Variable**: Automatically defines this variable in the main package (using git).
- **Auto-loads `.env`**: Loads environment variables from a `.env` file automatically.
- **Built-in Utilities**: Ships with a `utils.py` file for common utility functions.
---
## 🔧 Customization
Modify this template by editing:
- `copier.yml`: Adjust or add configuration options.
- `pyproject.toml`: Define dependencies, linting, and testing configurations.
- `.pre-commit-config.yaml`: Manage pre-commit hooks.
- `setup.sh`: Modify automation steps.
---
## 📝 License
This project is licensed under the **MIT License**. See LICENSE for more details.
---
### Support
For issues or suggestions, open an issue on GitHub: https://github.com/grok-ai/py-template/issues
---
## Maintainers
- Valentino Maiorca [@Flegyas](https://github.com/Flegyas)