# Flask MVC
<div align="center">
[](https://github.com/marcuxyz/flask-mvc)
[](https://github.com/marcuxyz/flask-mvc/actions)
[](https://github.com/marcuxyz/flask-mvc/blob/main/LICENSE)
[](https://pypi.org/project/flask_mvc/)
[](https://pypi.org/project/flask_mvc/)
[](https://pypi.org/project/flask_mvc/)
[](https://github.com/psf/black)
**Transform your Flask application into a structured MVC architecture with powerful CLI tools**
[Installation](#installation) •
[Quick Start](#quick-start) •
[Documentation](https://marcuxyz.github.io/flask-mvc) •
[Examples](#examples) •
[Contributing](#contributing)
</div>
## 🚀 Features
- **🏗️ MVC Architecture**: Clean separation of concerns with Models, Views, and Controllers
- **⚡ CLI Generator**: Powerful command-line tools to generate controllers, models, and more
- **🎨 Template System**: Professional templates with Flask best practices
- **🔧 Flexible Configuration**: Customizable paths and settings via environment variables
- **📝 Type Safety**: Full type hints support for better development experience
- **🧪 Testing Ready**: Built-in support for testing with comprehensive error handling
- **📖 Auto Documentation**: Generated code includes professional docstrings
- **🌐 API & Web Support**: Content negotiation for both web and API responses
## 📦 Installation
### Using pip
```bash
pip install flask_mvc
```
### Using Poetry
```bash
poetry add flask_mvc
```
### Development Installation
```bash
git clone https://github.com/marcuxyz/flask-mvc.git
cd flask_mvc
poetry install
```
## 🏃♂️ Quick Start
### Basic Setup
```python
from flask import Flask
from flask_mvc import FlaskMVC
app = Flask(__name__)
FlaskMVC(app)
if __name__ == "__main__":
app.run(debug=True)
```
### Using Application Factory Pattern
```python
from flask import Flask
from flask_mvc import FlaskMVC
mvc = FlaskMVC()
def create_app():
app = Flask(__name__)
# Initialize MVC extension
mvc.init_app(app, path='src') # Custom path (default: 'app')
return app
app = create_app()
```
### Generate Your First Controller
```bash
# Generate a basic controller
flask mvc generate controller home
# Generate controller in custom path
flask mvc generate controller user --path src/controllers
# Force overwrite existing controller
flask mvc generate controller admin --force
```
This creates a professional controller with CRUD operations:
```python
"""HomeController - Generated by Flask MVC CLI."""
from flask import render_template, jsonify, request
from typing import Any, Dict, Optional, Union
class HomeController:
"""Controller for handling home related requests."""
def index(self) -> Union[str, Dict[str, Any]]:
"""Display the index page."""
if request.is_json or request.accept_mimetypes.accept_json:
return jsonify({
"message": "Hello from HomeController!",
"controller": "home",
"action": "index"
})
return "Hello from HomeController!"
# Complete CRUD methods included...
```
## 📁 Project Structure
Flask MVC encourages a clean project structure:
```
your-project/
├── app/ # Main application directory
│ ├── __init__.py
│ ├── controllers/ # Controllers directory
│ │ ├── __init__.py
│ │ ├── home_controller.py
│ │ └── user_controller.py
│ ├── models/ # Models directory (optional)
│ │ └── user.py
│ ├── views/ # Templates directory
│ │ ├── layouts/
│ │ ├── home/
│ │ └── user/
│ └── routes.py # Route definitions
├── tests/ # Test directory
├── requirements.txt # Dependencies
└── app.py # Application entry point
```
## 🛠️ CLI Commands
Flask MVC provides powerful CLI commands for rapid development:
### Controller Generation
```bash
# Basic controller
flask mvc generate controller blog
# API controller
flask mvc generate controller api_v1_users
# Controller with custom path
flask mvc generate controller admin --path admin/controllers
# Force overwrite
flask mvc generate controller posts --force
```
### Available Options
| Option | Short | Description |
|--------|-------|-------------|
| `--path` | `-p` | Custom path for generated files |
| `--force` | `-f` | Overwrite existing files |
| `--help` | `-h` | Show command help |
## 🎯 Examples
### Web Application Controller
```python
class BlogController:
def index(self):
posts = Post.get_all()
return render_template('blog/index.html', posts=posts)
def show(self, id: int):
post = Post.get_by_id(id)
return render_template('blog/show.html', post=post)
```
### API Controller
```python
class ApiUserController:
def index(self):
users = User.get_all()
return jsonify([user.to_dict() for user in users])
def create(self):
data = request.get_json()
user = User.create(data)
return jsonify(user.to_dict()), 201
```
### Hybrid Controller (Web + API)
Generated controllers automatically handle both web and API requests:
```python
def index(self) -> Union[str, Dict[str, Any]]:
posts = Post.get_all()
if request.is_json or request.accept_mimetypes.accept_json:
return jsonify([post.to_dict() for post in posts])
return render_template('posts/index.html', posts=posts)
```
## ⚙️ Configuration
### Environment Variables
Customize Flask MVC behavior using environment variables:
```bash
# Custom paths
export FLASK_MVC_CONTROLLERS_PATH="src/controllers"
export FLASK_MVC_VIEWS_PATH="src/templates"
export FLASK_MVC_MODELS_PATH="src/models"
# Template settings
export FLASK_MVC_TEMPLATES_DIR="custom/templates"
export FLASK_MVC_FILE_ENCODING="utf-8"
```
### Programmatic Configuration
```python
from flask_mvc.core.config import CLIConfig
# Override default settings
CLIConfig.DEFAULT_CONTROLLERS_PATH = "src/controllers"
CLIConfig.DEFAULT_VIEWS_PATH = "src/templates"
```
## 🧪 Testing
Flask MVC is built with testing in mind:
```python
import pytest
from flask_mvc.core.generators import ControllerGenerator
from flask_mvc.core.exceptions import InvalidControllerNameError
def test_controller_generation():
generator = ControllerGenerator()
# Test valid controller generation
result = generator.generate("test", "/tmp/controllers")
assert result.exists()
# Test invalid name handling
with pytest.raises(InvalidControllerNameError):
generator.generate("123invalid")
```
## 📚 Documentation
- **[Full Documentation](https://marcuxyz.github.io/flask-mvc)** - Complete guide and API reference
- **[Quick Start Guide](https://marcuxyz.github.io/flask-mvc/quickstart)** - Get up and running fast
- **[Controller Guide](https://marcuxyz.github.io/flask-mvc/controllers)** - Working with controllers
- **[Router Guide](https://marcuxyz.github.io/flask-mvc/router)** - Route configuration
- **[CLI Reference](https://marcuxyz.github.io/flask-mvc/cli)** - Command-line tools
## 🤝 Contributing
We welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details.
### Development Setup
```bash
# Clone the repository
git clone https://github.com/marcuxyz/flask-mvc.git
cd flask_mvc
# Install dependencies
poetry install
# Run tests
poetry run pytest
# Run linting
poetry run black .
poetry run flake8
# Build documentation
poetry run mkdocs serve
```
### Reporting Issues
- **[Bug Reports](https://github.com/marcuxyz/flask-mvc/issues/new?template=bug_report.md)**
- **[Feature Requests](https://github.com/marcuxyz/flask-mvc/issues/new?template=feature_request.md)**
## 📋 Requirements
- **Python**: 3.10+
- **Flask**: 3.0+
- **Click**: 8.0+ (included with Flask)
- **Jinja2**: 3.0+ (included with Flask)
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🙏 Acknowledgments
- **Flask Community** - For the amazing web framework
- **Click Team** - For the excellent CLI framework
- **Contributors** - Everyone who has contributed to this project
## 📊 Stats
---
<div align="center">
Made with ❤️ by <a href="https://github.com/marcuxyz">Marcus Pereira</a>
</div>
Raw data
{
"_id": null,
"home_page": "https://github.com/marcuxyz/flask-mvc",
"name": "flask-mvc2",
"maintainer": "Marcus Pereira",
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": "marcus@negros.dev",
"keywords": "flask, mvc, web-framework, cli, generator, architecture, flask-extension, scaffold, crud, rest-api",
"author": "Marcus Pereira",
"author_email": "marcus@negros.dev",
"download_url": "https://files.pythonhosted.org/packages/35/af/78ddd5efc0dd43b28dbb0a7481b8fe6711a0c289f23e2c40e2f886c59cb1/flask_mvc2-0.1.0.tar.gz",
"platform": null,
"description": "# Flask MVC\n\n<div align=\"center\">\n\n\n\n[](https://github.com/marcuxyz/flask-mvc)\n[](https://github.com/marcuxyz/flask-mvc/actions)\n[](https://github.com/marcuxyz/flask-mvc/blob/main/LICENSE)\n[](https://pypi.org/project/flask_mvc/)\n[](https://pypi.org/project/flask_mvc/)\n[](https://pypi.org/project/flask_mvc/)\n[](https://github.com/psf/black)\n\n**Transform your Flask application into a structured MVC architecture with powerful CLI tools**\n\n[Installation](#installation) \u2022\n[Quick Start](#quick-start) \u2022\n[Documentation](https://marcuxyz.github.io/flask-mvc) \u2022\n[Examples](#examples) \u2022\n[Contributing](#contributing)\n\n</div>\n\n## \ud83d\ude80 Features\n\n- **\ud83c\udfd7\ufe0f MVC Architecture**: Clean separation of concerns with Models, Views, and Controllers\n- **\u26a1 CLI Generator**: Powerful command-line tools to generate controllers, models, and more\n- **\ud83c\udfa8 Template System**: Professional templates with Flask best practices\n- **\ud83d\udd27 Flexible Configuration**: Customizable paths and settings via environment variables\n- **\ud83d\udcdd Type Safety**: Full type hints support for better development experience\n- **\ud83e\uddea Testing Ready**: Built-in support for testing with comprehensive error handling\n- **\ud83d\udcd6 Auto Documentation**: Generated code includes professional docstrings\n- **\ud83c\udf10 API & Web Support**: Content negotiation for both web and API responses\n\n## \ud83d\udce6 Installation\n\n### Using pip\n\n```bash\npip install flask_mvc\n```\n\n### Using Poetry\n\n```bash\npoetry add flask_mvc\n```\n\n### Development Installation\n\n```bash\ngit clone https://github.com/marcuxyz/flask-mvc.git\ncd flask_mvc\npoetry install\n```\n\n## \ud83c\udfc3\u200d\u2642\ufe0f Quick Start\n\n### Basic Setup\n\n```python\nfrom flask import Flask\nfrom flask_mvc import FlaskMVC\n\napp = Flask(__name__)\nFlaskMVC(app)\n\nif __name__ == \"__main__\":\n app.run(debug=True)\n```\n\n### Using Application Factory Pattern\n\n```python\nfrom flask import Flask\nfrom flask_mvc import FlaskMVC\n\nmvc = FlaskMVC()\n\ndef create_app():\n app = Flask(__name__)\n\n # Initialize MVC extension\n mvc.init_app(app, path='src') # Custom path (default: 'app')\n\n return app\n\napp = create_app()\n```\n\n### Generate Your First Controller\n\n```bash\n# Generate a basic controller\nflask mvc generate controller home\n\n# Generate controller in custom path\nflask mvc generate controller user --path src/controllers\n\n# Force overwrite existing controller\nflask mvc generate controller admin --force\n```\n\nThis creates a professional controller with CRUD operations:\n\n```python\n\"\"\"HomeController - Generated by Flask MVC CLI.\"\"\"\n\nfrom flask import render_template, jsonify, request\nfrom typing import Any, Dict, Optional, Union\n\n\nclass HomeController:\n \"\"\"Controller for handling home related requests.\"\"\"\n\n def index(self) -> Union[str, Dict[str, Any]]:\n \"\"\"Display the index page.\"\"\"\n if request.is_json or request.accept_mimetypes.accept_json:\n return jsonify({\n \"message\": \"Hello from HomeController!\",\n \"controller\": \"home\",\n \"action\": \"index\"\n })\n return \"Hello from HomeController!\"\n\n # Complete CRUD methods included...\n```\n\n## \ud83d\udcc1 Project Structure\n\nFlask MVC encourages a clean project structure:\n\n```\nyour-project/\n\u251c\u2500\u2500 app/ # Main application directory\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u251c\u2500\u2500 controllers/ # Controllers directory\n\u2502 \u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2502 \u251c\u2500\u2500 home_controller.py\n\u2502 \u2502 \u2514\u2500\u2500 user_controller.py\n\u2502 \u251c\u2500\u2500 models/ # Models directory (optional)\n\u2502 \u2502 \u2514\u2500\u2500 user.py\n\u2502 \u251c\u2500\u2500 views/ # Templates directory\n\u2502 \u2502 \u251c\u2500\u2500 layouts/\n\u2502 \u2502 \u251c\u2500\u2500 home/\n\u2502 \u2502 \u2514\u2500\u2500 user/\n\u2502 \u2514\u2500\u2500 routes.py # Route definitions\n\u251c\u2500\u2500 tests/ # Test directory\n\u251c\u2500\u2500 requirements.txt # Dependencies\n\u2514\u2500\u2500 app.py # Application entry point\n```\n\n## \ud83d\udee0\ufe0f CLI Commands\n\nFlask MVC provides powerful CLI commands for rapid development:\n\n### Controller Generation\n\n```bash\n# Basic controller\nflask mvc generate controller blog\n\n# API controller\nflask mvc generate controller api_v1_users\n\n# Controller with custom path\nflask mvc generate controller admin --path admin/controllers\n\n# Force overwrite\nflask mvc generate controller posts --force\n```\n\n### Available Options\n\n| Option | Short | Description |\n|--------|-------|-------------|\n| `--path` | `-p` | Custom path for generated files |\n| `--force` | `-f` | Overwrite existing files |\n| `--help` | `-h` | Show command help |\n\n## \ud83c\udfaf Examples\n\n### Web Application Controller\n\n```python\nclass BlogController:\n def index(self):\n posts = Post.get_all()\n return render_template('blog/index.html', posts=posts)\n\n def show(self, id: int):\n post = Post.get_by_id(id)\n return render_template('blog/show.html', post=post)\n```\n\n### API Controller\n\n```python\nclass ApiUserController:\n def index(self):\n users = User.get_all()\n return jsonify([user.to_dict() for user in users])\n\n def create(self):\n data = request.get_json()\n user = User.create(data)\n return jsonify(user.to_dict()), 201\n```\n\n### Hybrid Controller (Web + API)\n\nGenerated controllers automatically handle both web and API requests:\n\n```python\ndef index(self) -> Union[str, Dict[str, Any]]:\n posts = Post.get_all()\n\n if request.is_json or request.accept_mimetypes.accept_json:\n return jsonify([post.to_dict() for post in posts])\n\n return render_template('posts/index.html', posts=posts)\n```\n\n## \u2699\ufe0f Configuration\n\n### Environment Variables\n\nCustomize Flask MVC behavior using environment variables:\n\n```bash\n# Custom paths\nexport FLASK_MVC_CONTROLLERS_PATH=\"src/controllers\"\nexport FLASK_MVC_VIEWS_PATH=\"src/templates\"\nexport FLASK_MVC_MODELS_PATH=\"src/models\"\n\n# Template settings\nexport FLASK_MVC_TEMPLATES_DIR=\"custom/templates\"\nexport FLASK_MVC_FILE_ENCODING=\"utf-8\"\n```\n\n### Programmatic Configuration\n\n```python\nfrom flask_mvc.core.config import CLIConfig\n\n# Override default settings\nCLIConfig.DEFAULT_CONTROLLERS_PATH = \"src/controllers\"\nCLIConfig.DEFAULT_VIEWS_PATH = \"src/templates\"\n```\n\n## \ud83e\uddea Testing\n\nFlask MVC is built with testing in mind:\n\n```python\nimport pytest\nfrom flask_mvc.core.generators import ControllerGenerator\nfrom flask_mvc.core.exceptions import InvalidControllerNameError\n\ndef test_controller_generation():\n generator = ControllerGenerator()\n\n # Test valid controller generation\n result = generator.generate(\"test\", \"/tmp/controllers\")\n assert result.exists()\n\n # Test invalid name handling\n with pytest.raises(InvalidControllerNameError):\n generator.generate(\"123invalid\")\n```\n\n## \ud83d\udcda Documentation\n\n- **[Full Documentation](https://marcuxyz.github.io/flask-mvc)** - Complete guide and API reference\n- **[Quick Start Guide](https://marcuxyz.github.io/flask-mvc/quickstart)** - Get up and running fast\n- **[Controller Guide](https://marcuxyz.github.io/flask-mvc/controllers)** - Working with controllers\n- **[Router Guide](https://marcuxyz.github.io/flask-mvc/router)** - Route configuration\n- **[CLI Reference](https://marcuxyz.github.io/flask-mvc/cli)** - Command-line tools\n\n## \ud83e\udd1d Contributing\n\nWe welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details.\n\n### Development Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/marcuxyz/flask-mvc.git\ncd flask_mvc\n\n# Install dependencies\npoetry install\n\n# Run tests\npoetry run pytest\n\n# Run linting\npoetry run black .\npoetry run flake8\n\n# Build documentation\npoetry run mkdocs serve\n```\n\n### Reporting Issues\n\n- **[Bug Reports](https://github.com/marcuxyz/flask-mvc/issues/new?template=bug_report.md)**\n- **[Feature Requests](https://github.com/marcuxyz/flask-mvc/issues/new?template=feature_request.md)**\n\n## \ud83d\udccb Requirements\n\n- **Python**: 3.10+\n- **Flask**: 3.0+\n- **Click**: 8.0+ (included with Flask)\n- **Jinja2**: 3.0+ (included with Flask)\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## \ud83d\ude4f Acknowledgments\n\n- **Flask Community** - For the amazing web framework\n- **Click Team** - For the excellent CLI framework\n- **Contributors** - Everyone who has contributed to this project\n\n## \ud83d\udcca Stats\n\n\n\n\n\n---\n\n<div align=\"center\">\nMade with \u2764\ufe0f by <a href=\"https://github.com/marcuxyz\">Marcus Pereira</a>\n</div>\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Transform Flask into a structured MVC architecture with powerful CLI tools",
"version": "0.1.0",
"project_urls": {
"Documentation": "https://marcuxyz.github.io/flask-mvc",
"Homepage": "https://github.com/marcuxyz/flask-mvc",
"Repository": "https://github.com/marcuxyz/flask-mvc"
},
"split_keywords": [
"flask",
" mvc",
" web-framework",
" cli",
" generator",
" architecture",
" flask-extension",
" scaffold",
" crud",
" rest-api"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "de593c634cf878a1dedd5a6b598746f7dfc2f25c6dcc152b2ec3e7e078351f01",
"md5": "08591d8e42f2571daa6df335b76b4917",
"sha256": "164d1ed77a6ce687a97645ca752b790a00d32e1f37497fb33f4d21fb3c802624"
},
"downloads": -1,
"filename": "flask_mvc2-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "08591d8e42f2571daa6df335b76b4917",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 18476,
"upload_time": "2025-07-14T11:54:43",
"upload_time_iso_8601": "2025-07-14T11:54:43.696841Z",
"url": "https://files.pythonhosted.org/packages/de/59/3c634cf878a1dedd5a6b598746f7dfc2f25c6dcc152b2ec3e7e078351f01/flask_mvc2-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "35af78ddd5efc0dd43b28dbb0a7481b8fe6711a0c289f23e2c40e2f886c59cb1",
"md5": "481457c4058d31389efea492af99a891",
"sha256": "7ba5cabd6b958de2742808dea510b4dc2a0bffa2084b5ffe02a827260794887e"
},
"downloads": -1,
"filename": "flask_mvc2-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "481457c4058d31389efea492af99a891",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 16759,
"upload_time": "2025-07-14T11:54:45",
"upload_time_iso_8601": "2025-07-14T11:54:45.176390Z",
"url": "https://files.pythonhosted.org/packages/35/af/78ddd5efc0dd43b28dbb0a7481b8fe6711a0c289f23e2c40e2f886c59cb1/flask_mvc2-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-14 11:54:45",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "marcuxyz",
"github_project": "flask-mvc",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "flask-mvc2"
}
JSON
