{"id":50215400,"url":"https://github.com/michalmaj/modern-python-project-guide","last_synced_at":"2026-05-26T08:41:45.043Z","repository":{"id":357582588,"uuid":"1237602807","full_name":"michalmaj/modern-python-project-guide","owner":"michalmaj","description":"Beginner-friendly guide to modern Python project structure with uv, pytest, Ruff, pyproject.toml, and GitHub Actions.","archived":false,"fork":false,"pushed_at":"2026-05-25T10:14:05.000Z","size":107,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-25T11:28:57.157Z","etag":null,"topics":["github-actions","pyproject-toml","pytest","python","python-project-template","ruff","tutorial","uv"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"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/michalmaj.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"docs/ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-13T10:33:24.000Z","updated_at":"2026-05-25T10:14:10.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/michalmaj/modern-python-project-guide","commit_stats":null,"previous_names":["michalmaj/modern-python-project-guide"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/michalmaj/modern-python-project-guide","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/michalmaj%2Fmodern-python-project-guide","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/michalmaj%2Fmodern-python-project-guide/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/michalmaj%2Fmodern-python-project-guide/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/michalmaj%2Fmodern-python-project-guide/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/michalmaj","download_url":"https://codeload.github.com/michalmaj/modern-python-project-guide/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/michalmaj%2Fmodern-python-project-guide/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33512320,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T03:12:49.672Z","status":"ssl_error","status_checked_at":"2026-05-26T03:12:47.976Z","response_time":63,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["github-actions","pyproject-toml","pytest","python","python-project-template","ruff","tutorial","uv"],"created_at":"2026-05-26T08:41:44.051Z","updated_at":"2026-05-26T08:41:45.035Z","avatar_url":"https://github.com/michalmaj.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Modern Python Project Guide\n\n[![CI](https://github.com/michalmaj/modern-python-project-guide/actions/workflows/ci.yml/badge.svg)](https://github.com/michalmaj/modern-python-project-guide/actions/workflows/ci.yml)\n\nA practical guide to building a clean, modern Python project with `uv`, `pytest`, `ruff`, `pyproject.toml`, GitHub Actions, and a pull request based workflow.\n\nThis repository is both a tutorial and a working example.\n\nIt shows how to turn a small Python idea into a maintainable project with:\n\n- a clear project structure,\n- dependency management with `uv`,\n- tests with `pytest`,\n- linting and formatting with `ruff`,\n- configuration in `pyproject.toml`,\n- continuous integration with GitHub Actions,\n- readable commits,\n- branches,\n- pull requests.\n\n## What you will learn\n\nAfter this guide, you will know how to:\n\n- create a small Python project with `uv`,\n- manage dependencies in `pyproject.toml`,\n- separate source code and tests,\n- run tests with `pytest`,\n- check and format code with Ruff,\n- run the same checks in GitHub Actions,\n- use a simple branch and pull request workflow.\n\n## Prerequisites\n\nThis guide is beginner-friendly, but it does not start from absolute zero.\n\nYou should be comfortable with:\n\n- basic Python syntax,\n- running commands in a terminal,\n- basic Git commands such as `clone`, `add`, `commit`, and `push`,\n- using GitHub at a basic level.\n\nYou do not need to know how to package Python projects, configure CI, or structure larger repositories.\nThose topics are introduced step by step.\n\n## Quick starts\n\nIn a hurry? Start here:\n\n- [uv quickstart](docs/quickstart_uv.md)\n- [Clone and CI quickstart](docs/quickstart_clone_and_ci.md)\n\n## Choose your path\n\n- I want to create a new project from scratch → read [uv quickstart](docs/quickstart_uv.md).\n- I cloned this repository and want to run it locally → read [Clone and CI quickstart](docs/quickstart_clone_and_ci.md).\n- I want to understand each file and tool step by step → start with the [full guide](#recommended-path).\n\n## Full guide\n\nThe full guide is organized as a step-by-step path.\n\nStart from the beginning if you want to understand why each tool and file is introduced.\n\n1. [Why this guide exists](docs/00_why_this_guide.md)\n2. [Project structure](docs/01_project_structure.md)\n3. [uv](docs/02_uv.md)\n4. [pyproject.toml](docs/03_pyproject_toml.md)\n5. [pytest](docs/04_pytest.md)\n6. [Ruff](docs/05_ruff.md)\n7. [GitHub Actions and CI](docs/06_github_actions.md)\n8. [Git, commits, branches, and pull requests](docs/07_git_commits_branches_prs.md)\n9. [Common beginner mistakes](docs/08_common_mistakes.md)\n10. [Project checklist](docs/09_checklist.md)\n\n## Common questions\n\nHave questions about the project decisions?\n\nRead [Common questions](docs/common_questions.md).\n\n## Glossary\n\nNew to project tooling terms?\n\nRead the [Glossary](docs/glossary.md).\n\n## Cheatsheet\n\nNeed commands only?\n\nRead the [Command cheatsheet](docs/cheatsheet.md).\n\n## Troubleshooting\n\nSomething does not work?\n\nRead the [Troubleshooting guide](docs/troubleshooting.md).\n\n## GitHub Actions logs\n\nCI failed and the logs look scary?\n\nRead [Reading GitHub Actions logs](docs/github_actions_logs.md).\n\n## Markdown review\n\nReviewing documentation changes?\n\nRead [Reviewing Markdown changes](docs/markdown_review.md).\n\n## Example pull request\n\nWant to see what a clear pull request looks like?\n\nRead [Example pull request](docs/example_pull_request.md).\n\n## From script to project\n\nWant to turn a single Python script into a maintainable project?\n\nRead [From script to project](docs/from_script_to_project.md).\n\n## Why these tools?\n\nThis guide uses a small set of tools that cover the basic needs of a modern Python project:\n\n- `uv` manages Python, dependencies, and the project environment.\n- `pytest` checks whether the code behaves correctly.\n- Ruff keeps code style and common issues under control.\n- GitHub Actions runs the same checks on GitHub.\n- Pull requests make changes easier to explain, review, and verify.\n\nThe goal is not to use tools for their own sake.\n\nThe goal is to build a workflow that is simple, reproducible, and easy to understand.\n\n## Example package\n\nThe repository contains a small example package:\n\n```text\nsrc/text_toolkit/\n```\n\nIn this guide, “package” means an importable Python package inside `src/`.\n\nBuilding and publishing installable Python distributions is a separate topic and is intentionally not covered in the first version of this guide.\n\nThe package is intentionally simple.\n\nIt is used to demonstrate project structure, tests, linting, formatting, and CI without adding unnecessary domain complexity.\n\nCurrent utilities include:\n\n- whitespace normalization,\n- word counting,\n- character counting.\n\n## Repository structure\n\n```text\nmodern-python-project-guide/\n├── .github/\n│   ├── workflows/\n│   │   └── ci.yml\n│   └── pull_request_template.md\n├── docs/\n│   ├── quickstart_uv.md\n│   ├── quickstart_clone_and_ci.md\n│   ├── 00_why_this_guide.md\n│   └── ...\n├── src/\n│   └── text_toolkit/\n├── tests/\n├── .gitignore\n├── .python-version\n├── CONTRIBUTING.md\n├── LICENSE\n├── README.md\n├── pyproject.toml\n└── uv.lock\n```\n\n## Local setup\n\nClone the repository:\n\n```bash\ngit clone https://github.com/michalmaj/modern-python-project-guide.git\ncd modern-python-project-guide\n```\n\nSync the environment:\n\n```bash\nuv sync\n```\n\nRun tests:\n\n```bash\nuv run pytest\n```\n\nRun Ruff linting:\n\n```bash\nuv run ruff check .\n```\n\nCheck formatting:\n\n```bash\nuv run ruff format --check .\n```\n\nFormat files:\n\n```bash\nuv run ruff format .\n```\n\n## Local quality checks\n\nBefore opening a pull request with code changes, run:\n\n```bash\nuv run ruff check .\nuv run ruff format --check .\nuv run pytest\n```\n\nIf formatting fails, run:\n\n```bash\nuv run ruff format .\n```\n\nThen repeat the checks.\n\n## Development workflow\n\nThis repository is built using small branches and pull requests.\n\nRecommended workflow:\n\n```text\nupdate main\ncreate a branch\nmake a small change\ncommit the change\npush the branch\nopen a pull request\nwait for CI\nreview the change\nmerge into main\ndelete the branch\n```\n\nExample:\n\n```bash\ngit switch main\ngit pull\ngit switch -c docs/example-change\n\n# edit files\n\ngit status\ngit add path/to/file.md\ngit commit -m \"docs: describe example change\"\ngit push -u origin docs/example-change\n```\n\nAfter merge:\n\n```bash\ngit switch main\ngit pull\ngit branch -d docs/example-change\n```\n\n## Who is this for?\n\nThis guide is for people who know basic Python and want to learn how to organize Python projects in a more professional way.\n\nIt is especially useful for:\n\n- students,\n- self-taught developers,\n- junior Python developers,\n- teachers preparing programming classes,\n- anyone moving from scripts to maintainable projects.\n\n## Do not optimize too early\n\nThis guide intentionally avoids adding too many tools at once.\n\nA smaller setup that you understand is better than a large template copied blindly.\n\nTools such as Docker, pre-commit hooks, type checkers, coverage reports, documentation generators, and release automation can be useful later.\n\nThey are not required to understand the foundation.\n\n## What this guide is not\n\nThis is not a complete Python packaging course.\n\nIt does not start with advanced topics such as:\n\n- publishing packages to PyPI,\n- Docker,\n- pre-commit hooks,\n- static type checking,\n- documentation generators,\n- release automation.\n\nThose topics may be added later.\n\nThe goal here is to build a clean foundation first.\n\n## Possible future chapters\n\nThe first version of this guide focuses on the project foundation.\n\nPossible future chapters may include:\n\n- static type checking with Pyright or mypy,\n- pre-commit hooks,\n- test coverage,\n- Python build systems and packaging,\n- building wheels and source distributions,\n- publishing packages to PyPI,\n- documentation sites,\n- release automation,\n- Docker for Python projects.\n\nThese topics are useful, but they are intentionally left out of the first path.\n\nThe goal is to understand the foundation before adding more layers.\n\n## Current status\n\nThis repository is built step by step.\n\nEach meaningful change should be introduced through a small branch and a pull request.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmichalmaj%2Fmodern-python-project-guide","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmichalmaj%2Fmodern-python-project-guide","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmichalmaj%2Fmodern-python-project-guide/lists"}