{"id":20731900,"url":"https://github.com/riad-azz/flask-template","last_synced_at":"2025-07-23T00:05:39.405Z","repository":{"id":153998110,"uuid":"596350576","full_name":"riad-azz/flask-template","owner":"riad-azz","description":"Flask starter template to help you build a scalable and maintanable project.","archived":false,"fork":false,"pushed_at":"2023-10-29T09:15:04.000Z","size":784,"stargazers_count":32,"open_issues_count":0,"forks_count":7,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-06-02T02:19:18.296Z","etag":null,"topics":["flask","flask-api","flask-app","flask-auth","flask-boilerplate","flask-caching","flask-cors","flask-docker","flask-dockerfile","flask-gunicorn","flask-rate-limiting","flask-redis","flask-starter","flask-staterapp","flask-structure","flask-template","flask-testing","flask-tests"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/riad-azz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2023-02-02T01:41:06.000Z","updated_at":"2025-02-05T17:30:33.000Z","dependencies_parsed_at":null,"dependency_job_id":"b29d9e69-02bd-41fe-911b-74eb34eda41f","html_url":"https://github.com/riad-azz/flask-template","commit_stats":null,"previous_names":[],"tags_count":0,"template":true,"template_full_name":null,"purl":"pkg:github/riad-azz/flask-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/riad-azz%2Fflask-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/riad-azz%2Fflask-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/riad-azz%2Fflask-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/riad-azz%2Fflask-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/riad-azz","download_url":"https://codeload.github.com/riad-azz/flask-template/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/riad-azz%2Fflask-template/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266592209,"owners_count":23953109,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-22T02:00:09.085Z","response_time":66,"last_error":null,"robots_txt_status":null,"robots_txt_updated_at":null,"robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["flask","flask-api","flask-app","flask-auth","flask-boilerplate","flask-caching","flask-cors","flask-docker","flask-dockerfile","flask-gunicorn","flask-rate-limiting","flask-redis","flask-starter","flask-staterapp","flask-structure","flask-template","flask-testing","flask-tests"],"created_at":"2024-11-17T05:16:55.098Z","updated_at":"2025-07-23T00:05:39.366Z","avatar_url":"https://github.com/riad-azz.png","language":"Python","readme":"# Flask Starter Template\n\nA simple Flask app starter template. This is my preference to bootstrap my Flask projects and not a must follow\nstructure, feel free to change whatever you dislike to fit what you are comfortable with.\n\n## Features\n\nHere is a list of the available features:\n\n- **Scalable Folder Structure**: The application employs an isolated app directory structure to ensure code\n  maintainability and readability.\n\n- **API Ready**: The template includes a ready-to-use API structure.\n\n- **Web UI**: The template includes a basic web user interface.\n\n- **User Authentication**: The template integrates Flask-Login for user authentication. It allows users to register, log\n  in, and log out. It provides session management, secure password hashing, and user session tracking.\n\n- **Rate Limiting**: To protect your application from abuse, rate limiting is enforced.\n\n- **CORS**: Cross-origin resource sharing (CORS) is configured to manage the server's shared resources.\n\n- **CACHING**: The template includes caching to optimize performance and reduce server load. Caching stores frequently\n  requested data temporarily, leading to faster API responses. It enhances user experience and helps handle high traffic\n  efficiently.\n\n- **Logging**: The application includes logging capabilities to record relevant events, errors, and messages. Logging\n  helps in monitoring and troubleshooting the application during development and production.\n\n- **Tests**: Unit tests are included to ensure the application's functionality and robustness.\n\n- **Docker Support**: A Dockerfile is included for building a Docker image of your application, facilitating easy\n  deployment and scaling.\n\n## Getting Started\n\n### Running The Application\n\n1.Clone the repository to your local machine:\n\n```bash\ngit clone https://github.com/riad-azz/flask-template \u0026\u0026 cd flask-template\n```\n\n2.Install the required dependencies:\n\n```bash\npip install -r requirements.txt\n```\n\n3.The application can be run with the following command:\n\n```bash\npython server.py\n```\n\n4.To enable the Ratelimit and Cache features make sure to copy the `.env.example` content and create a `.env` file:\n\n```.env\n# Flask Variables\nSECRET_KEY=\"YOUR-SECRET-KEY\"\n# Flask Ratelimit\nRATELIMIT_ENABLED=\"True\"\nRATELIMIT_STORAGE_URI=\"memory://\" # or redis://localhost:6379/0\n# Flask Cache\nCACHE_ENABLED=\"True\"\nCACHE_TYPE=\"SimpleCache\" # or RedisCache\nCACHE_STORAGE_URL=\"YOUR-REDIS-URL\" # Required only for CACHE_TYPE RedisCache\n```\n\n**Note**: for development you need to create a `.env.dev` file.\n\n### Running Tests\n\nYou can write tests in `flask-template/tests`, where you will also find some examples.\n\nTo run the tests simply use the command:\n\n```bash\npython -m pytest\n```\n\nYou can switch between running the tests from `.env.dev` _(development environment)_ or `.env` _(production environment)_ by going to `flask-template/tests/__init__.py` and changing the value of `FLASK_DEBUG`:\n\n```python\nimport os\n\n# Set 'False' to test with .env\n# Set 'True' to test with .env.dev\nos.environ[\"FLASK_DEBUG\"] = \"True\"\n```\n\n### Dockerize The Application\n\nTo run the application in Docker follow these steps:\n\n1.Install [Docker](https://www.docker.com/) on your machine.\n\n2.Build the Docker image for the application:\n\n```bash\ndocker build -t my-flask-image .\n```\n\n3.Run the Docker image:\n\n```bash\ndocker run -p 5000:5000 --name my-flask-container my-flask-image\n```\n\nOpen your browser and visit [http://localhost:5000](http://localhost:5000/) to see the website.\n\n## Flask API\n\nThis is how I like to set up my API in Flask. You might want to change this with `flask-restful` or whatever library\nthat suits you.\n\nYou can check `app/routes/api/tests.py` to get an idea of how the API should work.\n\n### API Schemas\n\nAll the schemas served with the API that are passed to the `success_response` must be **json serializable**. In\nthis example we use `BaseModel` from [pydantic](https://docs.pydantic.dev/latest/) which allows us to turn the model\ninto a dict using the `model_dump` function:\n\n```python\nfrom pydantic import BaseModel\n\n\nclass TestModel(BaseModel):\n    title: str\n    content: str\n```\n\n```python\n# Flask modules\nfrom flask import Blueprint\n\n# Local modules\nfrom app.schemas.test import TestModel\nfrom app.utils.api import success_response\n\ntests_bp = Blueprint(\"tests\", __name__, url_prefix=\"/tests\")\n\n\n@tests_bp.route(\"/success\", methods=['GET'])\ndef test_api_success():\n    data = TestModel(title=\"riad-azz\", content=\"Successful API response\")\n    data_dict = data.model_dump()\n    return success_response(data_dict, 200)\n```\n\n### Error handling\n\nFor API error handling use `werkzeug.exceptions` exception classes, and if you would like to create custom\nexceptions make sure that your exceptions inherit from `HTTPException`.\n\nThe API error handler can be found in `app/routes/api/__init__.py`:\n\n```python\n# Flask modules\nfrom flask import Blueprint\nfrom werkzeug.exceptions import HTTPException\nfrom flask_limiter.errors import RateLimitExceeded\n\n# Other modules\nimport logging\n\n# Local modules\nfrom app.utils.api import error_response\n\napi_bp = Blueprint(\"api\", __name__, url_prefix=\"/api\")\n\n\n@api_bp.errorhandler(Exception)\ndef handle_error(error):\n    if isinstance(error, RateLimitExceeded):\n        current_limit = error.limit.limit\n        return error_response(f\"Too many requests: {current_limit}\", 429)\n    elif isinstance(error, HTTPException):\n        return error_response(error.description, error.code)\n    else:\n        logging.error(error)\n        return error_response()\n```\n\nIf the exception is unknown the API will return a `Internal Server Error` by default from the `error_response`\nfunction.\n\n### API Response Examples\n\nRun the server and visit the following paths to check the API responses:\n\n- Success Request: [localhost:5000/api/tests/success](http://localhost:5000/api/tests/success)\n\n- Rate limited Request _(refresh to get rate\n  limited)_: [localhost:5000/api/tests/ratelimit](http://localhost:5000/api/tests/ratelimit)\n\n- Bad Request: [localhost:5000/api/tests/bad-request](http://localhost:5000/api/tests/bad-request)\n\n- Forbidden: [localhost:5000/api/tests/forbidden](http://localhost:5000/api/tests/forbidden)\n\n- Internal Server\n  Error: [localhost:5000/api/tests/internal-server-error](http://localhost:5000/api/tests/internal-server-error)\n\n- Unknown\n  Exception: [localhost:5000/api/tests/unknown-exception](http://localhost:5000/api/tests/unknown-exception)\n\n## Contributing\n\nContributions to improve this Flask app template are welcome. Please feel free to fork the repository, make changes, and\nsubmit a pull request.\n\n## License\n\nThis project is licensed under the terms of the MIT license. For more details, see the LICENSE file in the repository.\n","funding_links":[],"categories":["Flask"],"sub_categories":["Phaser"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Friad-azz%2Fflask-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Friad-azz%2Fflask-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Friad-azz%2Fflask-template/lists"}