| name | code-style |
| description | Python code style and knowledge graph conventions for materials-kg. Use when writing or reviewing Python code. |
Code Style & Conventions
Formatting
- Ruff (pyproject.toml): Line length 88, Python 3.11+, double quotes
- Imports: standard → third-party → local
- Type hints: on ALL function signatures
Naming
| Element | Convention | Example |
|---|
| Classes | PascalCase | MaterialsKGService |
| Functions | snake_case | resolve_entity |
| Variables | snake_case | entity_id |
| Constants | UPPER_SNAKE | MAX_RETRIES |
| Private | _prefix | _internal_state |
Module Pattern
from __future__ import annotations
import logging
logger = logging.getLogger(__name__)
class MyService:
"""Service description."""
def __init__(self, repo: MaterialsKGRepository) -> None:
self._repo = repo
Entity Types (8)
MATERIAL, EXPERIMENT, PROPERTY, MODE, EQUIPMENT, TEAM, DOCUMENT, TAG
Relation Types (9)
EVALUATES_MATERIAL, USES_MODE, MEASURES_PROPERTY, USES_EQUIPMENT, PERFORMED_BY, DOCUMENTED_IN, TAGGED_WITH, REFERENCES, RELATED_TO
Error Handling
- No silent exceptions: always log, never
except: pass
- No hardcoded fallbacks
- Safe defaults:
None, [], {}
Testing
- TDD: тест → код → рефакторинг (никогда код без теста)
- Location:
kg_engine/tests/
- Test behavior, not implementation
- Permanent (
test_*.py): регрессия, контракты — навсегда
- Temporary (
test_tmp_*.py): отладка, эксперименты — удалить после задачи
- Один тест = одно поведение, не дублируй
- Запуск:
python -m pytest kg_engine/tests/ -v
- Без tmp:
python -m pytest -m "not tmp" kg_engine/tests/ -v
DRY, Lean, Modular, Pythonic
