scallpy 0.1.0

A command-line tool to scaffold FastAPI projects, inspired by vitejs.

scallpy

A command-line tool to scaffold FastAPI projects, inspired by vitejs.

Overview

scallpy helps you quickly set up new FastAPI projects with sensible defaults, providing both a "clean" and a "structured" project template.

Installation

For Users

Requirements: Python 3.10 or higher.

To install scallpy and use it to create new projects, it's recommended to use pipx. This ensures scallpy and its dependencies are installed in an isolated environment without affecting your global Python packages.

pipx install scallpy

After installation, you can use the scallpy command globally.

For Developers (Contributing to scallpy)

If you want to contribute to scallpy or modify its source code:

1. Clone the repository:

   git clone https://github.com/jara505/fastapi-scallfolding.git
   cd fastapi-scallfolding
   

2. Create and activate a virtual environment:

   python3 -m venv venv
   source venv/bin/activate
   

3. Install in editable mode with dev dependencies:

   pip install -e ".[dev]"
   

4. Run tests:

   pytest
   

Note: For stability, use Poetry 1.x (e.g., pip install poetry==1.8.3) when working with generated projects. Poetry 2.x may have compatibility issues.

Usage

scallpy provides a create command to generate new FastAPI projects.

Interactive Mode

To create a project interactively, simply run:

scallpy create

The CLI will guide you through selecting a project name, type, and other options.

Non-Interactive Mode (with parameters)

You can also provide parameters directly to bypass interactive prompts, which is useful for scripting or quick setups.

scallpy create --name <project-name> --type <project-type> [--use-db] [--use-orm] [--path <output-path>]

Parameters:

• --name or -n: The name of your new FastAPI project. This will also be the name of the directory created for your project.
• --type or -t: The type of project structure to generate.
  • clean: A minimal FastAPI project with a single main.py file.
  • structured: A more organized FastAPI project with separate modules for API routes, core configuration, and models.
• --use-db (Optional): Include database support in the project. Use as a flag (e.g., --use-db).
• --use-orm (Optional): Include ORM (Object-Relational Mapper) support in the project. Use as a flag (e.g., --use-orm).
• --path or -p (Optional): The directory where the new project folder will be created. If not specified, the project will be created in the current working directory. If . is provided, the project folder will be created inside the current directory.

Example:

scallpy create --name my-awesome-api --type structured --path ./projects

Running Your Generated Project

After scallpy creates your project, it will provide specific instructions. Generally, the steps are:

1. Navigate into your new project directory:

   cd <your-project-name>
   

2. Install dependencies using Poetry:

   poetry install
   

3. Run the FastAPI development server:
   • For clean projects:

     poetry run uvicorn <your-project-name>.main:app --reload
     

   • For structured projects:

     poetry run uvicorn <your-project-name>.main:app --reload
     

   (Replace <your-project-name> with the actual name you gave your project).

Your FastAPI application will typically be available at http://127.0.0.1:8000.

Contributing

We welcome contributions! Please feel free to open issues or submit pull requests.

Testing

To run the test suite:

pytest

Ensure all tests pass before submitting pull requests.

License

This project is licensed under the MIT License.