ProjectStarter 🚀

ProjectStarter is a Python CLI tool created by Mohamed Ali for quickly creating ready-to-use project structures.

It helps developers avoid manually creating folders, files, virtual environments, installing framework dependencies, and preparing basic project documentation.

✨ Features

• 🐍 Create basic Python projects
• 🌐 Create Django projects
• ⚡ Create Flask projects
• 🚀 Create FastAPI projects
• 📦 Automatically create .venv for Django, Flask, and FastAPI projects
• ⬆️ Automatically upgrade pip
• 🔧 Automatically install required framework packages
• 📄 Automatically generate requirements.txt
• 🚫 Automatically generate .gitignore
• 📝 Automatically generate a README for generated projects
• 📋 List supported project types
• ℹ️ Show information about each project type
• 🩺 Check the ProjectStarter installation with doctor
• 🧪 Includes automated tests

---

📋 Supported Project Types

Project Type	Virtual Environment	Automatic Dependency Installation	Run Command
Python	No	No	python src/<project_name>/main.py
Django	Yes	Yes	python manage.py runserver
Flask	Yes	Yes	python run.py
FastAPI	Yes	Yes	uvicorn app.main:app --reload

The basic Python generator creates the project structure directly. Django, Flask, and FastAPI projects receive their own .venv and framework dependencies automatically.

---

📦 Installation

Install ProjectStarter from PyPI:

pip install projectstarter

Check that it is installed:

projectstarter --version

Show the available commands:

projectstarter --help

---

🚀 Usage

1. Create a project interactively

Run:

projectstarter create

ProjectStarter will show the available project types:

Choose a project type:

1. python
2. django
3. flask
4. fastapi

Then enter the number of the project type and the project name.

Example:

Enter your choice: 2
Enter project name: myproject

ProjectStarter will create the project automatically.

---

2. Create a Python project

Run:

projectstarter create python myproject

The generated structure is:

myproject/
├── src/
│   └── myproject/
│       ├── __init__.py
│       └── main.py
├── tests/
│   └── test_main.py
├── .gitignore
├── requirements.txt
└── README.md

Run the Python project

Windows:

python src/myproject/main.py

The generated application contains a simple main() function.

---

🌐 Django

Create a Django project:

projectstarter create django myproject

ProjectStarter automatically:

1. Creates the project directory.
2. Creates .venv.
3. Upgrades pip.
4. Installs Django.
5. Creates the Django project using the config package.
6. Creates requirements.txt.
7. Creates .gitignore.
8. Creates a project README.

The main structure is:

myproject/
├── .venv/
├── config/
│   ├── __init__.py
│   ├── asgi.py
│   ├── settings.py
│   ├── urls.py
│   └── wsgi.py
├── manage.py
├── requirements.txt
├── .gitignore
└── README.md

Activate the virtual environment

Windows:

cd myproject
.venv\Scripts\activate

macOS/Linux:

cd myproject
source .venv/bin/activate

Run Django

python manage.py runserver

Open:

http://127.0.0.1:8000/

---

⚡ Flask

Create a Flask project:

projectstarter create flask myproject

ProjectStarter automatically:

1. Creates the project directory.
2. Creates .venv.
3. Upgrades pip.
4. Installs Flask.
5. Creates the app package.
6. Creates templates and static directories.
7. Creates run.py.
8. Creates requirements.txt.
9. Creates .gitignore.
10. Creates a project README.

The generated structure is:

myproject/
├── .venv/
├── app/
│   ├── __init__.py
│   ├── templates/
│   └── static/
├── run.py
├── requirements.txt
├── .gitignore
└── README.md

Activate the virtual environment

Windows:

cd myproject
.venv\Scripts\activate

macOS/Linux:

cd myproject
source .venv/bin/activate

Run Flask

python run.py

Open:

http://127.0.0.1:5000/

---

🚀 FastAPI

Create a FastAPI project:

projectstarter create fastapi myproject

ProjectStarter automatically:

1. Creates the project directory.
2. Creates .venv.
3. Upgrades pip.
4. Installs FastAPI.
5. Installs Uvicorn.
6. Creates the app package.
7. Creates app/main.py.
8. Creates requirements.txt.
9. Creates .gitignore.
10. Creates a project README.

The generated structure is:

myproject/
├── .venv/
├── app/
│   ├── __init__.py
│   └── main.py
├── requirements.txt
├── .gitignore
└── README.md

Activate the virtual environment

Windows:

cd myproject
.venv\Scripts\activate

macOS/Linux:

cd myproject
source .venv/bin/activate

Run FastAPI

uvicorn app.main:app --reload

API:

http://127.0.0.1:8000/

Swagger documentation:

http://127.0.0.1:8000/docs

---

📋 List Project Types

To see all available generators:

projectstarter list

Example:

Available project types:

  python
  django
  flask
  fastapi

---

ℹ️ Project Information

Use the info command to see information about a generator.

Example:

projectstarter info django

Example output:

Django
──────────────────────────────
Description: Python web framework
Virtual environment: Yes
Automatic installation: Yes

Run:
    python manage.py runserver

You can also check other project types:

projectstarter info python
projectstarter info flask
projectstarter info fastapi

---

🩺 Doctor

ProjectStarter includes a built-in diagnostic command:

projectstarter doctor

It checks:

• Python
• Project registry
• Available generators
• Project information

Example:

ProjectStarter Doctor
──────────────────────────────
✓ Python
  Version: 3.x.x
✓ Registry
✓ Generators (4)
  - python
  - django
  - flask
  - fastapi
✓ Project Info
  All project information is available.

Everything looks good! ✓

---

🧪 Testing ProjectStarter

ProjectStarter uses pytest for automated testing.

Install pytest for development:

python -m pip install pytest

Run all tests:

python -m pytest

The test suite covers:

• Project name validation
• Generator registry
• Project information
• Python project generation
• Django project generation
• Flask project generation
• FastAPI project generation
• CLI commands
• Interactive project creation
• Doctor command

---

🏗️ ProjectStarter Development Structure

The ProjectStarter source code is organized as follows:

projectstarter/
├── projectstarter/
│   ├── __init__.py
│   ├── cli.py
│   ├── doctor.py
│   ├── generator.py
│   ├── registry.py
│   └── utils.py
│
├── templates/
│   └── python/
│       └── main.py
│
├── tests/
│   ├── test_cli.py
│   ├── test_generator.py
│   ├── test_registry.py
│   └── test_utils.py
│
├── README.md
├── LICENSE
└── pyproject.toml

Main Components

cli.py

Handles the command-line interface and commands such as:

create
list
info
doctor
--version

generator.py

Contains the project generation logic for:

• Python
• Django
• Flask
• FastAPI

It also handles virtual environment creation and dependency installation for supported frameworks.

registry.py

Contains the registered project generators and project information.

utils.py

Contains utility functions such as project-name validation.

doctor.py

Provides the projectstarter doctor diagnostic command.

tests/

Contains the automated test suite.

---

➕ Adding a New Generator

ProjectStarter is designed so that new project types can be added to the generator system.

A new generator generally needs:

1. A generator function in generator.py.
2. Registration in registry.py.
3. Project information in PROJECT_INFO.
4. Tests in tests/test_generator.py.
5. CLI tests when necessary.
6. Documentation in this README.

This keeps the CLI organized and makes the tool easier to extend.

---

🔐 Project Name Rules

ProjectStarter validates project names before creating projects.

Valid examples:

myproject
my_project
project123

Invalid examples:

my-project
my project
123project

Project names must use letters, numbers, and underscores and must not start with a number.

---

👨‍💻 Author

Mohamed Ali

ProjectStarter was created and is maintained by Mohamed Ali.

📞 Contact

For questions, suggestions, bug reports, or contributions, contact the project maintainer through GitHub.

• GitHub: https://github.com/hamada-cool
• Project Repository: https://github.com/hamada-cool/projectstarter
• Bug Reports / Issues: https://github.com/hamada-cool/projectstarter/issues
• Email: mohamedali32947@gmail.com
• Phone / WhatsApp: +918341391506 & +249919532947

You can also open a GitHub Issue if you find a bug or have an idea for improving ProjectStarter.

---

🤝 Contributing

Contributions, bug reports, suggestions, and improvements are welcome.

Before submitting changes:

1. Create a branch for your change.
2. Make your changes.
3. Run the test suite.
4. Make sure all tests pass.
5. Open a pull request.

Run tests with:

python -m pytest

---

📄 License

ProjectStarter is licensed under the MIT License.

See the LICENSE file for the complete license text.

---

🎯 Project Status

ProjectStarter currently supports:

• Python
• Django
• Flask
• FastAPI

The project is under active development, and more generators and features may be added in future releases.

---

⭐ Support the Project

If you find ProjectStarter useful, you can support the project by:

• ⭐ Starring the GitHub repository
• 🐛 Reporting bugs
• 💡 Suggesting features
• 🤝 Contributing code
• 📢 Sharing the project with other developers

---

ProjectStarter — Start your next Python project faster. 🚀

Created by Mohamed Ali.