[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6NQ2SH8042K4723THJ36AS5":3,"skill-same:01M6NQ2SH8042K4723THJ36AS5":82},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":23,"publishedAt":44,"linkOnly":45,"markdownContent":46,"markdownBody":47,"frontMatter":48,"refName":56,"commitSha":57,"skillDirectory":58,"forksCount":14,"repositoryHtmlUrl":59,"repositoryHomepageUrl":60,"ownerHtmlUrl":61,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":62,"install":63,"resources":76},"01M6NQ2SH8042K4723THJ36AS5","python-best-practices",null,"Python conventions and patterns — typing, testing, project layout, tooling. Use when writing or reviewing Python code, setting up a new Python project, or deciding on tooling, typing, or testing conventions.","projectious-work\u002Fprocesskit","projectious-work","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F263889726?v=4","01M6N97TJJ118WQ35CHRV8RD0E","projectious.work","01M6N97TPWJPF0BMKYQ4PBY5W8",0,"MIT","https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit\u002Fblob\u002Fmain\u002Fsrc\u002Fcontext\u002Fskills\u002Fengineering\u002Fpython-best-practices\u002FSKILL.md",[18],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000008","测试与质量","SCENARIO","使用场景",[24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43],"python","best practices","python best practices","tooling","python code","typing","python project","layout","project","testing conventions","conventions","patterns","best-practices","testing","up","use","work","engineering","code","writing","2026-11-10 10:12:30",false,"---\nname: python-best-practices\ndescription: |\n  Python conventions and patterns — typing, testing, project layout, tooling. Use when writing or reviewing Python code, setting up a new Python project, or deciding on tooling, typing, or testing conventions.\nmetadata:\n  processkit:\n    apiVersion: processkit.projectious.work\u002Fv2\n    id: SKILL-python-best-practices\n    version: \"1.1.0\"\n    created: 2026-04-06T00:00:00Z\n    category: engineering\n---\n\n# Python Best Practices\n\n## Intro\n\nModern Python is opinionated: `src\u002F` layout, `pyproject.toml`, type\nhints on public APIs, `pytest` for tests, `ruff` for lint and format.\nApply these conventions when writing or reviewing Python code.\n\n## Overview\n\n### Project layout\n\nUse the `src\u002F` layout. The package lives at `src\u002F\u003Cpackage>\u002F` with an\n`__init__.py`; tests live in a sibling `tests\u002F` tree mirroring the\npackage structure. Configuration goes in `pyproject.toml` — never\n`setup.py` or `setup.cfg`. Prefer `uv` for dependency management when\nthe project supports it; fall back to `pip-tools` or `poetry`\notherwise.\n\n```\nmy-project\u002F\n├── pyproject.toml\n├── src\u002F\n│   └── my_package\u002F\n│       ├── __init__.py\n│       └── core.py\n└── tests\u002F\n    └── test_core.py\n```\n\n### Type hints\n\nAdd type hints to all public function signatures and dataclass fields.\nUse `from __future__ import annotations` at the top of every module to\nenable modern syntax (PEP 563-style postponed evaluation) without\nruntime cost. Prefer `TypeAlias`, `Protocol`, and `dataclass` over raw\ndicts and tuples for non-trivial data shapes.\n\n### Testing with pytest\n\nTest files mirror the `src\u002F` tree: `src\u002Fmy_package\u002Ffoo.py` is tested\nby `tests\u002Ftest_foo.py`. Use fixtures for shared setup and `parametrize`\nfor variant testing. Name tests `test_\u003Cfunction>_\u003Cscenario>_\u003Cexpected>`\nso failures self-document.\n\n### Code style\n\nFormat with `ruff format`, lint with `ruff check`. Both replace older\ncombinations of black + isort + flake8 + pyupgrade. Prefer dataclasses\nor Pydantic models over plain dicts. Use `pathlib.Path` over\n`os.path`. Use f-strings over `.format()` or `%` formatting.\n\n### Error handling\n\nRaise specific exception classes, not generic `Exception`. Define\ncustom exception classes per domain (e.g.\n`UserNotFoundError(LookupError)`). Never write a bare `except:` —\nalways catch the specific exception type you expect.\n\n## Gotchas\n\nAgent-specific failure modes — provider-neutral pause-and-self-check items:\n\n- **Bare `except:` or catching `Exception` and silencing it.** A broad except that does nothing (or just logs) hides bugs, masks KeyboardInterrupt, and makes debugging impossible. Always catch the specific exception type; re-raise anything you didn't expect.\n- **Mutable default arguments.** `def foo(x=[]):` creates the list once at function-definition time, so all callers share the same list. The canonical fix is `def foo(x=None): if x is None: x = []`. This is a Python-specific trap that surprises engineers coming from other languages.\n- **`from module import *` at the top of a module.** Star imports pollute the namespace, hide the origin of names, and prevent tools from detecting unused imports. Use explicit imports; ruff catches violations.\n- **Mixing `os.path` and `pathlib.Path` in the same codebase.** `pathlib.Path` is the modern, readable API. Once adopted, `os.path` usage stands out as a maintenance signal. Pick one; default to `pathlib` for new code.\n- **Constructing SQL queries by string formatting.** f-strings and `%` formatting in SQL produce SQL injection vulnerabilities. Always use parameterized queries, regardless of whether the input comes from a user.\n- **Missing `from __future__ import annotations` in modules with complex types.** Without this import, forward references and complex annotations are evaluated at import time, causing `NameError` on circular references. Add it to every module that uses type hints.\n- **Making a library async by default without a sync entry point.** Sync callers cannot easily wrap an async library; they must run an event loop manually. Default libraries to sync and provide async variants, or offer a sync wrapper via `asyncio.to_thread`.\n\n## Full reference\n\n### `pyproject.toml` skeleton\n\n```toml\n[project]\nname = \"my-package\"\nversion = \"0.1.0\"\ndescription = \"Short description.\"\nrequires-python = \">=3.10\"\ndependencies = [\n    \"httpx>=0.27\",\n]\n\n[project.optional-dependencies]\ndev = [\n    \"pytest>=8.0\",\n    \"pytest-cov>=4.0\",\n    \"ruff>=0.5\",\n]\n\n[build-system]\nrequires = [\"hatchling\"]\nbuild-backend = \"hatchling.build\"\n\n[tool.ruff]\nline-length = 80\ntarget-version = \"py310\"\n\n[tool.ruff.lint]\nselect = [\"E\", \"F\", \"I\", \"B\", \"UP\", \"SIM\"]\n\n[tool.pytest.ini_options]\ntestpaths = [\"tests\"]\n```\n\n### Type-hint patterns\n\n| Use case | Pattern |\n|---|---|\n| Function returning nothing | `def foo() -> None:` (not `-> ()` or omitted) |\n| Optional value | `x: int \\| None` (PEP 604, modern) over `Optional[int]` |\n| Iterable input | `Iterable[T]` for read-only consumption; `list[T]` only when mutation is needed |\n| Callback \u002F interface | `Protocol` over abstract base class |\n| Frozen value | `dataclass(frozen=True)` or `tuple` |\n| Factory return type | The interface (`Protocol` or ABC), not the concrete class |\n\n### Testing conventions\n\n- **Fixtures over setup methods.** pytest fixtures are composable and\n  scoped; `unittest`-style `setUp\u002FtearDown` is not.\n- **One assertion per test, ideally.** When more is genuinely needed,\n  use `pytest.subtests` or split.\n- **No mocking the unit under test.** Mock the boundary\n  (HTTP client, database driver, clock). Mocking the function you're\n  testing means you're testing the mock.\n- **Coverage is a smoke alarm, not a goal.** Aim for meaningful\n  coverage of branching logic, not 100% line coverage.\n\n### Async vs sync\n\nUse `async`\u002F`await` when the workload is genuinely I\u002FO bound and the\necosystem supports it (HTTP servers, network clients, databases with\nasync drivers). Do **not** make a library async by default — sync\ncallers cannot easily wrap async code, but async callers can wrap\nsync code via `asyncio.to_thread`. Default to sync; opt into async\nwhen concurrency is the point.\n\n### Anti-patterns to avoid\n\n- **Bare `except:`** — catch specific types\n- **`from module import *`** — explicit imports only\n- **Mutable default arguments** (`def foo(x=[]):`) — use `None` and\n  initialize inside\n- **Generic exception handling that swallows errors** — at minimum\n  log + re-raise; never silently `pass`\n- **Mixing tabs and spaces** — ruff catches this; never bypass\n- **`os.path.join` over `Path \u002F Path`** — pathlib is the modern API\n- **Shell-style string concatenation for SQL** — parametrized queries\n  always\n\n### When to break the rules\n\nEvery rule above has exceptions. Pin yourself to the rule until you\nunderstand why it exists; only then are you qualified to break it.\nCommon legitimate exceptions: type-stub files (`.pyi`) intentionally\nomit type hints in body, scientific code uses `numpy` arrays which\nhave their own typing patterns, scripts under ~50 lines may skip the\n`src\u002F` layout.\n","# Python Best Practices\n\n## Intro\n\nModern Python is opinionated: `src\u002F` layout, `pyproject.toml`, type\nhints on public APIs, `pytest` for tests, `ruff` for lint and format.\nApply these conventions when writing or reviewing Python code.\n\n## Overview\n\n### Project layout\n\nUse the `src\u002F` layout. The package lives at `src\u002F\u003Cpackage>\u002F` with an\n`__init__.py`; tests live in a sibling `tests\u002F` tree mirroring the\npackage structure. Configuration goes in `pyproject.toml` — never\n`setup.py` or `setup.cfg`. Prefer `uv` for dependency management when\nthe project supports it; fall back to `pip-tools` or `poetry`\notherwise.\n\n```\nmy-project\u002F\n├── pyproject.toml\n├── src\u002F\n│   └── my_package\u002F\n│       ├── __init__.py\n│       └── core.py\n└── tests\u002F\n    └── test_core.py\n```\n\n### Type hints\n\nAdd type hints to all public function signatures and dataclass fields.\nUse `from __future__ import annotations` at the top of every module to\nenable modern syntax (PEP 563-style postponed evaluation) without\nruntime cost. Prefer `TypeAlias`, `Protocol`, and `dataclass` over raw\ndicts and tuples for non-trivial data shapes.\n\n### Testing with pytest\n\nTest files mirror the `src\u002F` tree: `src\u002Fmy_package\u002Ffoo.py` is tested\nby `tests\u002Ftest_foo.py`. Use fixtures for shared setup and `parametrize`\nfor variant testing. Name tests `test_\u003Cfunction>_\u003Cscenario>_\u003Cexpected>`\nso failures self-document.\n\n### Code style\n\nFormat with `ruff format`, lint with `ruff check`. Both replace older\ncombinations of black + isort + flake8 + pyupgrade. Prefer dataclasses\nor Pydantic models over plain dicts. Use `pathlib.Path` over\n`os.path`. Use f-strings over `.format()` or `%` formatting.\n\n### Error handling\n\nRaise specific exception classes, not generic `Exception`. Define\ncustom exception classes per domain (e.g.\n`UserNotFoundError(LookupError)`). Never write a bare `except:` —\nalways catch the specific exception type you expect.\n\n## Gotchas\n\nAgent-specific failure modes — provider-neutral pause-and-self-check items:\n\n- **Bare `except:` or catching `Exception` and silencing it.** A broad except that does nothing (or just logs) hides bugs, masks KeyboardInterrupt, and makes debugging impossible. Always catch the specific exception type; re-raise anything you didn't expect.\n- **Mutable default arguments.** `def foo(x=[]):` creates the list once at function-definition time, so all callers share the same list. The canonical fix is `def foo(x=None): if x is None: x = []`. This is a Python-specific trap that surprises engineers coming from other languages.\n- **`from module import *` at the top of a module.** Star imports pollute the namespace, hide the origin of names, and prevent tools from detecting unused imports. Use explicit imports; ruff catches violations.\n- **Mixing `os.path` and `pathlib.Path` in the same codebase.** `pathlib.Path` is the modern, readable API. Once adopted, `os.path` usage stands out as a maintenance signal. Pick one; default to `pathlib` for new code.\n- **Constructing SQL queries by string formatting.** f-strings and `%` formatting in SQL produce SQL injection vulnerabilities. Always use parameterized queries, regardless of whether the input comes from a user.\n- **Missing `from __future__ import annotations` in modules with complex types.** Without this import, forward references and complex annotations are evaluated at import time, causing `NameError` on circular references. Add it to every module that uses type hints.\n- **Making a library async by default without a sync entry point.** Sync callers cannot easily wrap an async library; they must run an event loop manually. Default libraries to sync and provide async variants, or offer a sync wrapper via `asyncio.to_thread`.\n\n## Full reference\n\n### `pyproject.toml` skeleton\n\n```toml\n[project]\nname = \"my-package\"\nversion = \"0.1.0\"\ndescription = \"Short description.\"\nrequires-python = \">=3.10\"\ndependencies = [\n    \"httpx>=0.27\",\n]\n\n[project.optional-dependencies]\ndev = [\n    \"pytest>=8.0\",\n    \"pytest-cov>=4.0\",\n    \"ruff>=0.5\",\n]\n\n[build-system]\nrequires = [\"hatchling\"]\nbuild-backend = \"hatchling.build\"\n\n[tool.ruff]\nline-length = 80\ntarget-version = \"py310\"\n\n[tool.ruff.lint]\nselect = [\"E\", \"F\", \"I\", \"B\", \"UP\", \"SIM\"]\n\n[tool.pytest.ini_options]\ntestpaths = [\"tests\"]\n```\n\n### Type-hint patterns\n\n| Use case | Pattern |\n|---|---|\n| Function returning nothing | `def foo() -> None:` (not `-> ()` or omitted) |\n| Optional value | `x: int \\| None` (PEP 604, modern) over `Optional[int]` |\n| Iterable input | `Iterable[T]` for read-only consumption; `list[T]` only when mutation is needed |\n| Callback \u002F interface | `Protocol` over abstract base class |\n| Frozen value | `dataclass(frozen=True)` or `tuple` |\n| Factory return type | The interface (`Protocol` or ABC), not the concrete class |\n\n### Testing conventions\n\n- **Fixtures over setup methods.** pytest fixtures are composable and\n  scoped; `unittest`-style `setUp\u002FtearDown` is not.\n- **One assertion per test, ideally.** When more is genuinely needed,\n  use `pytest.subtests` or split.\n- **No mocking the unit under test.** Mock the boundary\n  (HTTP client, database driver, clock). Mocking the function you're\n  testing means you're testing the mock.\n- **Coverage is a smoke alarm, not a goal.** Aim for meaningful\n  coverage of branching logic, not 100% line coverage.\n\n### Async vs sync\n\nUse `async`\u002F`await` when the workload is genuinely I\u002FO bound and the\necosystem supports it (HTTP servers, network clients, databases with\nasync drivers). Do **not** make a library async by default — sync\ncallers cannot easily wrap async code, but async callers can wrap\nsync code via `asyncio.to_thread`. Default to sync; opt into async\nwhen concurrency is the point.\n\n### Anti-patterns to avoid\n\n- **Bare `except:`** — catch specific types\n- **`from module import *`** — explicit imports only\n- **Mutable default arguments** (`def foo(x=[]):`) — use `None` and\n  initialize inside\n- **Generic exception handling that swallows errors** — at minimum\n  log + re-raise; never silently `pass`\n- **Mixing tabs and spaces** — ruff catches this; never bypass\n- **`os.path.join` over `Path \u002F Path`** — pathlib is the modern API\n- **Shell-style string concatenation for SQL** — parametrized queries\n  always\n\n### When to break the rules\n\nEvery rule above has exceptions. Pin yourself to the rule until you\nunderstand why it exists; only then are you qualified to break it.\nCommon legitimate exceptions: type-stub files (`.pyi`) intentionally\nomit type hints in body, scientific code uses `numpy` arrays which\nhave their own typing patterns, scripts under ~50 lines may skip the\n`src\u002F` layout.\n",{"name":5,"metadata":49,"description":55},{"processkit":50},{"id":51,"created":52,"version":53,"category":41,"apiVersion":54},"SKILL-python-best-practices",1775433600000,"1.1.0","processkit.projectious.work\u002Fv2","Python conventions and patterns — typing, testing, project layout, tooling. Use when writing or reviewing Python code, setting up a new Python project, or deciding on tooling, typing, or testing conventions.\n","main","7231f100e266e30d2c1699ecde5c00602471dc3c","src\u002Fcontext\u002Fskills\u002Fengineering\u002Fpython-best-practices","https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit","https:\u002F\u002Fprojectious-work.github.io\u002Fprocesskit\u002F","https:\u002F\u002Fgithub.com\u002Fprojectious-work","2026-11-11 23:24:18",{"source":8,"skillName":5,"commands":64,"prompt":74,"zipAvailable":75},[65,68,71],{"tool":66,"command":67},"npx","npx skills add projectious-work\u002Fprocesskit --skill python-best-practices",{"tool":69,"command":70},"bunx","bunx skills add projectious-work\u002Fprocesskit --skill python-best-practices",{"tool":72,"command":73},"pnpm","pnpm dlx skills add projectious-work\u002Fprocesskit --skill python-best-practices","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit\u002Fblob\u002Fmain\u002Fsrc\u002Fcontext\u002Fskills\u002Fengineering\u002Fpython-best-practices\u002FSKILL.md",true,[77],{"path":78,"resourceType":79,"resourceTypeDesc":80,"sizeBytes":14,"sourceHtmlUrl":81},"scripts\u002F.gitkeep","SCRIPT","脚本","https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit\u002Fblob\u002Fmain\u002Fsrc\u002Fcontext\u002Fskills\u002Fengineering\u002Fpython-best-practices\u002Fscripts\u002F.gitkeep",[83,90,97,103,128,148],{"skillNo":84,"name":85,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":86,"categories":87,"keywords":88,"publishedAt":89},"01M7665G2ED3624R3X93304265","standard-ui-design","https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fstandard-ui-design\u002FSKILL.md",[],[],"2026-11-12 13:55:43",{"skillNo":91,"name":92,"nameZh":6,"description":93,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":94,"categories":95,"keywords":96,"publishedAt":89},"01M76651QTC6W0HJ4AFW2MMR3V","standard-agent-use","Company standard for working with AI agents. Use when deciding what to delegate to agents, capturing open work, keeping agent memory or knowledge notes, improving an agent workflow, or introducing agent work in a team or for a client.","https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fstandard-agent-use\u002FSKILL.md",[],[],{"skillNo":98,"name":99,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":100,"categories":101,"keywords":102,"publishedAt":89},"01M76650NN4T8P241021NBR64S","standard-agent-building","https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fstandard-agent-building\u002FSKILL.md",[],[],{"skillNo":104,"name":105,"nameZh":6,"description":106,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":107,"categories":108,"keywords":112,"publishedAt":44},"01M6X5MTC89B4ZGXW3JVSQCPF8","skill-management","Manage Skill package manifests as v1 ontology entities.","https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit\u002Fblob\u002Fmain\u002Fsrc\u002Fcontext\u002Fskills\u002Fprocesskit\u002Fskill-management\u002FSKILL.md",[109],{"categoryNo":110,"categoryName":111,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000023","Skill与智能体开发",[113,114,115,116,117,118,40,119,120,121,122,123,105,124,125,126,127],"management","skill management","ontology","v1","create","as","transition","get","manage","update","alpha","list","package","skill package","manifests",{"skillNo":129,"name":130,"nameZh":6,"description":131,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":132,"categories":133,"keywords":135,"publishedAt":44},"01M6X5MCV74NHW5MEDNHZRF2C8","schema-management","Manage generated processkit schema contracts through deterministic MCP rebuild and inspection workflows.","https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit\u002Fblob\u002Fmain\u002Fsrc\u002Fcontext\u002Fskills\u002Fprocesskit\u002Fschema-management\u002FSKILL.md",[134],{"categoryNo":110,"categoryName":111,"taxonomyType":21,"taxonomyTypeDesc":22},[136,137,113,138,139,140,141,142,143,144,145,146,40,120,121,123,147],"schema","schema management","contract","rebuild","contracts","workflows","wed","generated","MCP","validation","deterministic","mode",{"skillNo":149,"name":150,"nameZh":6,"description":151,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":152,"categories":153,"keywords":154,"publishedAt":44},"01M6X5M5G6YJ96AMZGSCZJ1D13","proposition-management","Record claims, risks, beliefs, world facts, WSJF estimates, and assumptions through the Proposition interface.","https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit\u002Fblob\u002Fmain\u002Fsrc\u002Fcontext\u002Fskills\u002Fprocesskit\u002Fproposition-management\u002FSKILL.md",[],[155,113,156,157,117,158,159,160,40,120,161,162,122,163,123,164,165,166,167,168],"proposition management","proposition","interface","claims","record","world","creation","event","WSJF","index","updates","query","facts","log"]