{"id":20846755,"url":"https://github.com/kimgoetzke/practice-fastapi-score-calculator","last_synced_at":"2026-05-06T19:35:37.183Z","repository":{"id":159352829,"uuid":"634612320","full_name":"kimgoetzke/practice-fastapi-score-calculator","owner":"kimgoetzke","description":"A project to practice Python and FastAPI.","archived":false,"fork":false,"pushed_at":"2023-04-30T17:38:54.000Z","size":108,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-01-19T05:29:13.605Z","etag":null,"topics":["alembic","fastapi","postgresql","pydantic","pytest","python","sqlalchemy"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kimgoetzke.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-04-30T17:34:02.000Z","updated_at":"2023-05-20T19:17:46.000Z","dependencies_parsed_at":"2023-05-27T00:30:19.379Z","dependency_job_id":null,"html_url":"https://github.com/kimgoetzke/practice-fastapi-score-calculator","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kimgoetzke%2Fpractice-fastapi-score-calculator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kimgoetzke%2Fpractice-fastapi-score-calculator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kimgoetzke%2Fpractice-fastapi-score-calculator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kimgoetzke%2Fpractice-fastapi-score-calculator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kimgoetzke","download_url":"https://codeload.github.com/kimgoetzke/practice-fastapi-score-calculator/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243213852,"owners_count":20254879,"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","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":["alembic","fastapi","postgresql","pydantic","pytest","python","sqlalchemy"],"created_at":"2024-11-18T02:17:52.016Z","updated_at":"2026-05-06T19:35:37.125Z","avatar_url":"https://github.com/kimgoetzke.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# The FastAPI Score Calculator Project\n\nThis repo was created in March 2023 to practice Python by building a FastAPI app. It contains a basic web app with endpoints to manage and calculate well-known bankruptcy predicting scores based on financial input data.\n\nAPI documentation can be found at `http://localhost:8080/docs` while the app is running.\n\n## Contents\n- [Disclaimer](#disclaimer)\n- [How to start](#how-to-start)\n- [How to use](#how-to-use)\n- [Data schema](#data-schema)\n- [Key technologies used](#key-technologies-used)\n\n## Disclaimer\n1. **Security:** To minimise the scope of this exercise, security concerns have been ignored.\n2. **Best practice:** This was the first time I worked in Python, so I will have inevitably and inappropriately used some Java common practice or simply violated Python best practice.\n\n## How to start\n_Run app locally_\n1. Once you have a cloned repository open in your terminal, update the `.env` file and line 58 of `alembic.ini` with your local Postgres credentials \n2. Run `docker compose -f docker-compose.db-only up` to start the Postgres database container\n3. Activate the virtual environment with `venv\\Scripts\\activate`.\n4. Start the app with `uvicorn main:app --reload --port 8080`\n5. Open `http://localhost:8080/docs` in your browser to open the API documentation and test the API\n\n_Run app in container_\n1. Once you have a cloned repository open in your terminal, change `sqlalchemy.url` (line 58) in `alembic.ini` to `postgresql+psycopg2://postgres:password@db/python_fastapi_db`.\n2. Run `docker compose up` to download/build all images and start the three containers (FastAPI web app, Postgres database, and pgAdmin as database admin tool for troubleshooting/testing)\n3. Open `http://localhost:8080/docs` in your browser to open the API documentation and test the API\n\n\n## How to use\n### Sample data\n\nOnce running, the app will preload the following sample data. This is because the model requires any score/company related request to be linked to an existing country. Companies and scores are then created automatically.\n\n###### Countries\n```\n[\n  {\n    \"alpha_2_iso_code\": \"GB\",\n    \"name\": \"United Kingdom\",\n    \"company_number_regex\": \"^([a-zA-Z]{2}[0-9]{6}|[0-9]{8})$\",\n  },\n  {\n    \"alpha_2_iso_code\": \"US\",\n    \"name\": \"United States\",\n    \"company_number_regex\": \"^[0-9]{2}-[0-9]{7}]$\",\n  }\n]\n```\n- `company_number_regex` is used to validate company numbers against the requirements for this country\n- If no `company_number_regex` is provided when creating a new country, the default value (`^.*$`) will be used\n\n\n### Key endpoint: \n#### POST `company/{country_iso_code}/{company_number}`\n\n__Expected input__\n1. `{country_iso_code}` - 2 alphabetic characters, upper case. Alpha 2 ISO standard. Must exist in the database.\n2. `{company_number}` - Valid company number. Validated with regex pattern on the country e.g. `^([a-zA-Z]{2}[0-9]{6}|[0-9]{8})$` for UK.\n3. JSON body - example:\n```\n{\n    \"financials\":[\n        {\n            \"year\": 2020,\n            \"ebit\": 123.45,\n            \"equity\": 234.56,\n            \"retained_earnings\": 345.67,\n            \"sales\": 1234.56,\n            \"total_assets\": 345.67,\n            \"total_liabilities\": 456.78,\n            \"working_capital\": 23.45\n        }\n    ]\n}\n```\n#### Requirements\n- A country with the provided `{country_iso_code}` parameter must exist (see _Sample data_)\n\n#### Notes\n- If the country does not exist, this endpoint will automatically create a new company using `company_number` and `country_iso_code` with `name`=`Unknown`\n- No financial data will be stored in the database - see section [Data schema](#data-schema) below\n\n#### Returns\nJSON body example:\n```\n{\n    \"scores\":[\n        {\n            \"year\": 2020,\n            \"zscore\": 6.54,\n        }\n    ]\n}\n```\n\n### Additional endpoints\n_Only used to test the key endpoint. Please refer to the OpenAPI documentation for further detail (including required fields and validation). This section only intends to give a high-level summary._\n\n#### Company\n- __GET `company/{country_iso_code}/{company_number}`__ - returns score report containing all scores for the company\n- __GET `company`__ - get list of all companies\n- __POST `company`__ - create and store a new company\n\n#### Country\n- __GET `country/{country_iso_code}`__ - get company by `country_iso_code` (Alpha 2)\n- __GET `country`__ - get list of all countries\n- __POST `country`__ - create new country\n\n## Data schema\n\n_Note: `financials` are not stored in the database as they are not to be useful to retain in the scope of this app. Considerations for currencies and additional P\u0026L and balance sheet data would have to be included, likely resulting in several, separate tables that are not relevant for this practice exercise._ \n\n![diagram-data-schema.png](diagram-data-schema.png)\n\n## Key technologies used\n\n1. Python 3.11 / Docker\n2. FastAPI (API framework)\n3. Psycopg2-binary 2.9.5 (PostgreSQL database adapter)\n4. Pydantic 1.10.5 (data validation)\n5. Pytest (testing)\n6. Alembic (data migration)\n7. SQLAlchemy (ORM)\n8. Poetry (dependency management - _not used in containerised app_)\n9. PostgreSQL container (database)\n10. pgAdmin container (database admin platform)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkimgoetzke%2Fpractice-fastapi-score-calculator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkimgoetzke%2Fpractice-fastapi-score-calculator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkimgoetzke%2Fpractice-fastapi-score-calculator/lists"}