archived-MoviePilot/docs/rules/07-naming-conventions.md

07 — Naming Conventions

All new code must follow these conventions. Consistent naming is how the codebase communicates intent without comments.

---

Files

Context	Convention	Examples
Python source files	snake_case.py	download_chain.py, qbittorrent.py
Module package directories	snake_case/	qbittorrent/, synologychat/
Test files	test_<domain>.py	test_download_chain.py, test_subscribe_endpoint.py
Alembic migrations	Auto-generated by Alembic; do not rename	20240101_add_column.py
Skill directories	<kebab-case>/	transfer-failed-retry/, moviepilot-cli/

---

Classes

Context	Convention	Examples
Chain classes	<Domain>Chain	DownloadChain, SearchChain, SubscribeChain
Module classes	<Backend>Module	QbittorrentModule, EmbyModule, TelegramModule
Oper (data access) classes	<Model>Oper	SubscribeOper, SystemConfigOper, TransferHistoryOper
Helper classes	<Domain>Helper	TorrentHelper, DirectoryHelper, MessageHelper
Pydantic schema models	PascalCase, noun-focused	MediaInfo, TorrentInfo, DownloadingTorrent
SQLAlchemy model classes	PascalCase, singular noun	Subscribe, TransferHistory, SystemConfig
Enum classes	PascalCase	MediaType, EventType, ModuleType
Manager classes	<Domain>Manager	ModuleManager, PluginManager, EventManager
General classes	PascalCase	MetaInfo, Context, ChainBase

---

Functions and Methods

Context	Convention	Examples
All functions and methods	snake_case	get_subscribe, run_module, on_config_changed
Private methods	_snake_case (leading underscore)	_submit_download_added_task, _parse_result
Event handler methods	on_<event_name> or descriptive	on_transfer_complete, handle_config_changed
Module interface methods	Match _ModuleBase contract	init_module, init_setting, get_name, get_type, test, stop
Oper methods	Verb + noun	get, add, update, delete, list

---

Variables and Parameters

Context	Convention	Examples
Local variables	snake_case	torrent_info, media_type, download_dir
Instance attributes	snake_case	self.download_history, self.config
Constants (module-level)	UPPER_SNAKE_CASE	DEFAULT_EVENT_PRIORITY, MIN_EVENT_CONSUMER_THREADS
Private variables	_snake_case (leading underscore)	_instance, _lock
Type variables	PascalCase with TypeVar	T = TypeVar("T")

---

Enums

Context	Convention	Examples
Enum class name	PascalCase	MediaType, TorrentStatus, EventType
Enum members	PascalCase (for complex enums)	MediaType.MOVIE, EventType.TransferComplete
String enum values	Match the domain language	MediaType.MOVIE = '电影', TorrentStatus.TRANSFER = '可转移'
SystemConfigKey values	Match the config key as a string	SystemConfigKey.RssUrls = "RssUrls"

---

Configuration and Settings

Context	Convention	Examples
Settings / ConfigModel fields	UPPER_SNAKE_CASE	API_TOKEN, LLM_MODEL, QB_HOST
SystemConfigKey enum members	PascalCase	SystemConfigKey.RssUrls, SystemConfigKey.SubscribeFilter
Environment variable names	UPPER_SNAKE_CASE	AI_AGENT_ENABLE, DB_TYPE

---

API Endpoints and Routers

Context	Convention	Examples
Endpoint function names	snake_case, verb-first	get_subscribe_list, add_download, delete_history
URL path segments	kebab-case or snake_case matching existing patterns	/api/v1/subscribe, /api/v1/transfer/history
Router tags	Match the resource domain name	"subscribe", "download", "media"

---

Anti-Patterns

Wrong	Correct
class downloadchain:	class DownloadChain:
class QBModule:	class QbittorrentModule:
def GetSubscribe():	def get_subscribe():
TORRENT_info = ...	torrent_info = ...
def handleConfigChanged():	def on_config_changed(): or def handle_config_changed():
SystemConfigOper().get("RssUrls")	SystemConfigOper().get(SystemConfigKey.RssUrls)
class subscribe_oper:	class SubscribeOper:

Last Updated: 2026-05-25