TicketMetric-tool 0.1.2__py3-none-any.whl

ticketmetric_tool-0.1.2.dist-info/METADATA

@@ -0,0 +1,304 @@
+Metadata-Version: 2.4
+Name: TicketMetric_tool
+Version: 0.1.2
+Summary: Shared internal helpers: config, logging, Mongo, retries, migrations, jobs, notifications.
+License-Expression: LicenseRef-Proprietary
+Project-URL: Source, https://github.com/aryansingh3/common_internal_tool
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: pymongo>=4.6.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: requests>=2.31.0
+Provides-Extra: flask
+Requires-Dist: Flask>=2.3.0; extra == "flask"
+Provides-Extra: logging
+Requires-Dist: pretty-pie-log>=0.1.0; extra == "logging"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4; extra == "dev"
+Requires-Dist: mongomock>=4.1; extra == "dev"
+
+# TicketMetric_tool
+
+Shared internal helpers for the API, the scrapers, the crons and one-off migrations.
+
+> **Two names, on purpose.** The pip distribution is
+> `TicketMetric_tool`; the import is the short `tmcommon`.
+> Same convention as `pip install python-dateutil` / `import dateutil`, so call
+> sites stay readable instead of carrying a 36 character prefix.
+>
+> ```bash
+> pip install TicketMetric_tool
+> ```
+> ```python
+> from tmcommon.jobs import Job
+> ```
+>
+> To make them identical instead, rename `src/tmcommon/` and update the two
+> `[project.scripts]` paths in `pyproject.toml`.
+
+Design rule: **the library ships mechanism, the app keeps policy and schema.** Connection
+handling, batching, retries and migration plumbing live here. Collection names, index
+definitions and business queries stay in the app.
+
+It is importable with no Flask installed, no Slack configured and no database reachable,
+because migrations and scrapers need it too.
+
+## Install
+
+```bash
+# from the repo
+pip install -e /path/to/common_internal_tool            # core
+pip install -e ".[flask,logging]"                       # API services
+
+# straight from GitHub
+pip install "git+https://github.com/aryansingh3/common_internal_tool.git@main"
+```
+
+Pin a release once there is one, rather than tracking `main`:
+
+```bash
+pip install "git+https://github.com/aryansingh3/common_internal_tool.git@v0.1.0"
+```
+
+Build a wheel to hand around or host yourself:
+
+```bash
+python -m build --wheel        # dist/ticketmetric_tool-0.1.2-py3-none-any.whl
+```
+
+## Getting changes into the consuming repos
+
+pip does not watch GitHub. Installing takes a snapshot, so a push to `main` changes
+nothing in an environment that already installed the package. Pick the workflow that
+matches where you are:
+
+**Developing the library and an app together.** Clone once, install editable, and every
+`git pull` is live with no reinstall. This is the only setup where changes really are
+automatic.
+
+```bash
+git clone https://github.com/aryansingh3/common_internal_tool.git
+pip install -e ../common_internal_tool
+```
+
+**Pulling the latest `main` into an environment.** pip caches aggressively, so an
+`--upgrade` alone often appears to do nothing when the version string has not moved:
+
+```bash
+pip install --upgrade --force-reinstall --no-cache-dir \
+  "git+https://github.com/aryansingh3/common_internal_tool.git@main"
+```
+
+**Deployments.** Pin a tag, never `main`. A deploy that resolves `main` is not
+reproducible, and the same Dockerfile will produce different images on different days.
+
+```
+# requirements.txt
+TicketMetric_tool @ git+https://github.com/aryansingh3/common_internal_tool.git@v0.1.2
+```
+
+Bumping that pin is then a reviewable one-line diff, which is what you want for a library
+several services depend on.
+
+### Cutting a release
+
+```bash
+# bump version in pyproject.toml, commit, then
+git tag v0.2.0 && git push origin v0.2.0
+```
+
+The release workflow verifies the tag matches `pyproject.toml`, runs the suite, builds the
+wheel and sdist, and attaches them to a GitHub Release.
+
+### The private-repo gotcha
+
+This repo is private, so anything without your local git credentials, CI, Docker builds,
+production hosts, cannot clone it. A `pip install git+https://...` there fails with an
+authentication error. The usual fixes:
+
+- a deploy key on this repo, with the private key as a secret in the consumer, using the
+  `git+ssh://git@github.com/...` form
+- a fine-grained PAT with read access, injected as
+  `git+https://${TOKEN}@github.com/...`
+- or build the wheel in CI and push it to a private index
+
+For Docker, mount the credential as a build secret rather than baking a token into a layer.
+
+## Python support
+
+**3.9 through 3.13.** 3.9 is the floor because the Flask API runs on it, so nothing here
+uses 3.10+ syntax: no PEP 604 `X | Y` unions, no `match` statements. CI compiles every
+file on each version to enforce that, including modules the tests do not import.
+
+## Tests
+
+```bash
+python3 run_tests.py
+```
+
+No pytest needed, so the suite runs on an interpreter carrying only the core
+dependencies. The files are valid pytest modules too. A test file whose optional
+dependency is missing prints `SKIP` and passes, so no Flask is not a failure.
+
+Verified locally on 3.9.6 and 3.11.15; 3.10, 3.12 and 3.13 are covered by the CI matrix.
+
+`tests/fake_mongo.py` is a small in-memory `Collection` covering only the operations these
+modules use, so lock and batch logic is testable without mongomock and without pointing a
+test at a real cluster.
+
+## Environment
+
+| variable | required | purpose |
+|---|---|---|
+| `SERVICE_NAME` | recommended | identifies the service in logs and alerts |
+| `APP_ENV` | no | `dev`/`local`/`test`/`staging` suppress Slack; anything else is production |
+| `LOG_DIR` | no | absolute log directory, defaults to `<cwd>/logs` |
+| `LOG_LEVEL` | no | defaults to `DEBUG` |
+| `MONGODB_URI` | when using mongo | default cluster |
+| `MONGODB_URI_<ALIAS>` | no | extra clusters, e.g. `MONGODB_URI_STAGING` |
+| `SLACK_WEBHOOK_URL` | when notifying | absent means notifications are skipped, not an error |
+
+## Modules
+
+| module | what it gives you |
+|---|---|
+| `config` | typed env access that raises at point of use, not on import |
+| `logging` | `get_logger(name)`, cached, absolute log dir, falls back to stdlib when `pretty_pie_log` is absent |
+| `context` | correlation id and extra fields via ContextVar, so a cron traceback is traceable |
+| `exceptions` | `BaseAPIException` and the HTTP subclasses, dependency-free |
+| `serialization` | one JSON encoder for ObjectId and datetime, plus `to_jsonable` |
+| `retry` | `@retry` with exponential backoff and jitter |
+| `timing` | `timed()`, `@timeit`, and `Stopwatch` for multi-phase jobs |
+| `mongo.connection` | lazy multi-cluster registry, `DatabaseRouter` for the live/historical split |
+| `mongo.batch` | chunked `insert_many` / `bulk_write` that separates duplicate keys from real errors |
+| `mongo.iterate` | `iter_by_id` keyset paging, no cursor timeouts, resumable |
+| `mongo.checkpoint` | watermarks so incremental jobs resume instead of guessing a `--since` |
+| `migrations` | versioned migrations with an applied record, a lock and dry-run |
+| `jobs` | scheduled work: expiring locks, run history, heartbeats, overdue detection |
+| `notify.slack` | error alerts, framework-agnostic, context supplied by the app |
+| `flask_ext` | `init_app(app)` for correlation ids and error handlers |
+
+## Jobs and crons
+
+A `Job` gets a lock, a run row, a status document with heartbeat, a correlation id, a
+checkpoint, failure alerting and timing. Records use the field names already in
+`vc_worker_runs` and `vc_worker_status`, so existing queries keep working.
+
+```python
+from tmcommon.jobs import Job
+
+class SectionRosterJob(Job):
+    name = 'tm_section_roster'
+    description = 'Fold new TM snapshots into the section roster'
+    lock_ttl_seconds = 1800
+
+    def run(self, ctx):
+        since = ctx.checkpoint.get()
+        processed = 0
+        for event_id in events_since(since):
+            update_roster(event_id)
+            processed += 1
+            if not ctx.heartbeat(processed=processed):
+                break          # lease lost, another process took over
+        ctx.checkpoint.advance(newest_seen)
+        return {'events': processed}
+```
+
+Run it in-process, replacing the hand-rolled worker threads:
+
+```python
+from tmcommon.jobs import Scheduler
+
+scheduler = Scheduler(db)
+scheduler.add(SectionRosterJob(), interval_seconds=86400)
+scheduler.add(CleanupJob(), interval_seconds=86400, initial_delay_seconds=300)
+scheduler.start()
+```
+
+Or as a one-shot under system cron or a Kubernetes CronJob, with the same recording:
+
+```bash
+tm-job run     --package jobs --db tickets --name tm_section_roster
+tm-job status  --db tickets
+tm-job overdue --db tickets --expect tm_section_roster=86400,cleanup_worker=86400
+```
+
+`overdue` exits non-zero when a job is late, so a monitor can alert on it. That is the
+failure currently invisible: `cron.py` is a bare `while True` loop, and if that process
+dies every schedule inside it stops with no signal.
+
+**Why the lock matters here.** `app.py` starts the workers at module scope, in the `else`
+branch gunicorn takes, so every web worker process starts its own copy. Four gunicorn
+workers run four cleanup loops concurrently today. Under `Scheduler` all four still start
+and exactly one does the work per tick; the rest record `skipped`.
+
+## Flask wiring
+
+```python
+from tmcommon.flask_ext import init_app, flask_context_provider
+from tmcommon.notify import register_context_provider
+
+init_app(app)
+register_context_provider(lambda: {**flask_context_provider(),
+                                   'User': get_request_user().email})
+```
+
+`BaseAPIException` becomes its `to_dict()` response and is logged at warning. Anything else
+is treated as a bug: logged with a traceback, sent to Slack, returned as a 500. A 404 or 405
+is neither.
+
+## Migrations
+
+```python
+# migrations/m20261001_section_roster.py
+from tmcommon.migrations import Migration
+
+class SectionRoster(Migration):
+    version = '20261001_section_roster'
+    description = 'Build tm_section_roster from ticketmaster_detail_data'
+
+    def up(self, db, dry_run=False):
+        count = db.ticketmaster_detail_data.estimated_document_count()
+        if dry_run:
+            return {'would_scan': count}
+        ...
+        return {'events': 412, 'sections': 9304}
+```
+
+```bash
+tm-migrate status --package migrations --db tickets
+tm-migrate up     --package migrations --db tickets            # dry run
+tm-migrate up     --package migrations --db tickets --apply
+```
+
+Writes need `--apply`. Deliberate, given these run against collections with millions of rows.
+
+## Deliberately not here
+
+- **Collection accessors and index definitions.** Your `DatabaseConnection._create_indexes()`
+  is app schema. Declare it in the app and call it at startup.
+- **`DatabaseManager` business queries.** `get_user_from_email`, `get_analytics` and the
+  venue lookups are domain logic, not shared mechanism.
+- **Domain models** such as `APIUser` and `Membership`.
+
+## Roadmap
+
+Not built yet, in rough priority order:
+
+1. `http` client: session with retry, proxy rotation and UA rotation. Both repos already carry
+   `proxies.json` and `user_agent.json` plus their own rotation code.
+2. `pipeline` base: extract/transform/load with stats and failure reporting, to replace the
+   per-spider boilerplate.
+3. `ratelimit`: token bucket for upstream politeness.
+4. `dates`: `est_to_utc`, `convert_utc_to_timezone`, currently duplicated in both repos.
+5. `mongo.upsert`: find-or-create keyed on an alternate identity, the gap behind the duplicate
+   events bug.
+6. `schema`: declarative model base with `to_dict` / `from_dict` and validation.
+7. Test helpers: `mongomock` fixtures and a fake clock.

ticketmetric_tool-0.1.2.dist-info/RECORD

@@ -0,0 +1,29 @@
+tmcommon/__init__.py,sha256=UcHce8oYKiZ1D1PotwXR7yjWNS7fydfZx9B16ggYe1Q,653
+tmcommon/config.py,sha256=yECQwfKukJXPF-bYnuDSAHVBMwLK47mldclhJ-k8ijg,2323
+tmcommon/context.py,sha256=HFlr7agBH7bvQUM8UN8a5aFtSKY6-4XMOTlkFejIPNg,2267
+tmcommon/exceptions.py,sha256=PsXp2Qx519JB0wO9Q5G-121em3d2obAleXmczvppw1g,2924
+tmcommon/flask_ext.py,sha256=y0zM23e6c09DGKK5XLersgj2hV_dD7Tk6k8xBUcrcdk,3516
+tmcommon/logging.py,sha256=kCpqRWIOHmCIshxMLUzh6RKwykOY7Je6NaJtKKahOAQ,4882
+tmcommon/retry.py,sha256=gnMPiTLUW_l0W1M2iRYmHgllN65r8aNkSIsPKTlwKbo,2982
+tmcommon/serialization.py,sha256=2dtq7w_zNBlXtrSS5V39dRuHD5QaxhYaDRJOfMp6Rso,2637
+tmcommon/timing.py,sha256=NgJzajp_r9xJi38mpF80Q33lB33hXkx8Eme2TPJkUJ8,2546
+tmcommon/jobs/__init__.py,sha256=RvvBIyMiDZ9DzCo5iq-jcwwbX0hhUQpAUvMBq6dRkDQ,1467
+tmcommon/jobs/cli.py,sha256=P4rIWNvrM4i9Bt9C9Hk0K8I1AEQftaXJNfquo2aUCiE,3950
+tmcommon/jobs/job.py,sha256=je74RnqpdgTKWGahirti5NGtpIgGdwYAHmfUxHhK-SE,8656
+tmcommon/jobs/lock.py,sha256=jHYs4EHjVZBOPdSF-X37ayEFZ8dbZo3U77cvm4ZHbbU,4866
+tmcommon/jobs/scheduler.py,sha256=7LIqQMNDehYjK4qkxh4Sh4KKA7SlcHDyu_TJu9VQbAY,5331
+tmcommon/migrations/__init__.py,sha256=YNNV1wY5LQstoF6AAhX7alNTA90TgR-4nGzOh1YogJs,1064
+tmcommon/migrations/cli.py,sha256=9XD5yf9SEtoaboBDnnDxs-UqRGEQ3kstJsKBitICypg,2905
+tmcommon/migrations/runner.py,sha256=lL-Z_UnQuhnLRAAaMdHbwbN_5TkGZM5re8PdAaCdOrk,7752
+tmcommon/mongo/__init__.py,sha256=6XoKanYPmmBP5AQcg7TcX0Eu-1hXyVY1dz6F8EslpXQ,566
+tmcommon/mongo/batch.py,sha256=4FLjjxK5uvV_WqmaEV6Herd9JXLvz3gV4tKX5xgCV3U,4386
+tmcommon/mongo/checkpoint.py,sha256=Dh_OZJwh2Q9wOcn_wD9znvuc-reOLhy9VmBGAdhJ0dc,2818
+tmcommon/mongo/connection.py,sha256=SpPSEFfBdeZE3WjA17qM2VlGdLA24_rB6x8Z_jlFK-E,4287
+tmcommon/mongo/iterate.py,sha256=AuRBXcVVQV-_5PPBpc1FSxkgN8mUnxOULoI-6nuVP_8,3712
+tmcommon/notify/__init__.py,sha256=9Ir_62wdjYiMJBwTXx_c3fpUrCfPXF-OthED9aNZBpQ,118
+tmcommon/notify/slack.py,sha256=B4AF_1FZEzUqEgoZgBu48JrpqAYsfWYNRLFe_4LFO14,6846
+ticketmetric_tool-0.1.2.dist-info/METADATA,sha256=IeVWuyPNxdm_KGLWy8NvJJGeLXIYjGEXtbA8unpN2eE,11879
+ticketmetric_tool-0.1.2.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+ticketmetric_tool-0.1.2.dist-info/entry_points.txt,sha256=yOjQFXY0j2GfmO0v4vSaTCFaNKUBFf2HB4PQB3SGBp4,92
+ticketmetric_tool-0.1.2.dist-info/top_level.txt,sha256=0hjLLI3FAhbXAb8UlrJe4hEtHPC726-1pfpRD9Gc1TQ,9
+ticketmetric_tool-0.1.2.dist-info/RECORD,,

ticketmetric_tool-0.1.2.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

ticketmetric_tool-0.1.2.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+tm-job = tmcommon.jobs.cli:main
+tm-migrate = tmcommon.migrations.cli:main

ticketmetric_tool-0.1.2.dist-info/top_level.txt

@@ -0,0 +1 @@
+tmcommon

tmcommon/__init__.py

@@ -0,0 +1,27 @@
+"""Shared internal helpers.
+
+Deliberately importable without Flask, without Slack configured, and without a
+reachable database, so the same package serves the API, the scrapers, the crons
+and one-off migrations. Submodules are imported on demand rather than eagerly
+here, for that reason.
+"""
+
+from . import config, context, exceptions, serialization
+from .logging import get_logger
+from .retry import retry
+from .timing import Stopwatch, timed, timeit
+
+__version__ = '0.1.2'
+
+__all__ = [
+    'config',
+    'context',
+    'exceptions',
+    'serialization',
+    'get_logger',
+    'retry',
+    'Stopwatch',
+    'timed',
+    'timeit',
+    '__version__',
+]

tmcommon/config.py

@@ -0,0 +1,78 @@
+"""Typed environment access that fails loudly at the point of use.
+
+Deliberately not a module-level singleton that raises on import. A migration
+script should be able to ``import tmcommon`` without a Slack webhook configured,
+and a scraper should not need the API's variables. Every getter either has a
+default or raises only when something actually asks for it.
+"""
+
+import os
+from typing import List, Optional
+
+from dotenv import load_dotenv
+
+load_dotenv()
+
+_TRUTHY = {'1', 'true', 'yes', 'on'}
+
+# Values of APP_ENV that mean "not production". Anything else is treated as
+# production, so a typo fails safe rather than silently disabling alerting.
+_NON_PROD = {'dev', 'development', 'local', 'test', 'staging'}
+
+
+class ConfigError(RuntimeError):
+    """A required setting is missing or unusable."""
+
+
+def get(name: str, default: Optional[str] = None) -> Optional[str]:
+    value = os.getenv(name)
+    return default if value is None or value == '' else value
+
+
+def require(name: str) -> str:
+    value = get(name)
+    if value is None:
+        raise ConfigError(
+            f"{name} is not set. Add it to the environment or the .env file."
+        )
+    return value
+
+
+def get_bool(name: str, default: bool = False) -> bool:
+    value = get(name)
+    return default if value is None else value.strip().lower() in _TRUTHY
+
+
+def get_int(name: str, default: Optional[int] = None) -> Optional[int]:
+    value = get(name)
+    if value is None:
+        return default
+    try:
+        return int(value)
+    except ValueError:
+        raise ConfigError(f"{name} must be an integer, got {value!r}")
+
+
+def get_list(name: str, default: Optional[List[str]] = None) -> List[str]:
+    value = get(name)
+    if value is None:
+        return list(default or [])
+    return [part.strip() for part in value.split(',') if part.strip()]
+
+
+def app_env() -> str:
+    return (get('APP_ENV', 'production') or 'production').strip().lower()
+
+
+def is_dev_mode() -> bool:
+    """True when this process should skip side effects such as Slack alerts."""
+    return app_env() in _NON_PROD
+
+
+def service_name() -> str:
+    """Identifies the calling service in logs and alerts.
+
+    Set SERVICE_NAME per deployment. It is the one piece of identity a shared
+    library cannot infer for itself.
+    """
+    return get('SERVICE_NAME', 'unknown-service')

tmcommon/context.py

@@ -0,0 +1,73 @@
+"""Correlation id that survives outside a web request.
+
+Your current Slack notifier reads ``flask.g.request_id``, which means a traceback
+from a cron, a scraper or a migration arrives with "N/A" and cannot be tied back
+to anything. A ContextVar works in all of them, and is also coroutine- and
+thread-safe, so a worker pool does not leak ids between jobs.
+"""
+
+import uuid
+from contextlib import contextmanager
+from contextvars import ContextVar
+from typing import Dict, Iterator, Optional
+
+_correlation_id: ContextVar[Optional[str]] = ContextVar('tmcommon_correlation_id', default=None)
+_extra: ContextVar[Optional[Dict[str, object]]] = ContextVar('tmcommon_extra', default=None)
+
+
+def new_id() -> str:
+    return uuid.uuid4().hex
+
+
+def set_correlation_id(value: Optional[str] = None) -> str:
+    cid = value or new_id()
+    _correlation_id.set(cid)
+    return cid
+
+
+def get_correlation_id() -> Optional[str]:
+    """Current id, falling back to Flask's ``g.request_id`` when one is set.
+
+    The fallback keeps services that already populate ``g`` working unchanged.
+    """
+    cid = _correlation_id.get()
+    if cid:
+        return cid
+    try:
+        from flask import g, has_request_context
+
+        if has_request_context():
+            return getattr(g, 'request_id', None)
+    except Exception:
+        pass
+    return None
+
+
+def set_extra(**fields: object) -> None:
+    """Attach fields that should ride along on logs and alerts, e.g. event_id."""
+    current = dict(_extra.get() or {})
+    current.update(fields)
+    _extra.set(current)
+
+
+def get_extra() -> Dict[str, object]:
+    return dict(_extra.get() or {})
+
+
+@contextmanager
+def correlation(value: Optional[str] = None, **fields: object) -> Iterator[str]:
+    """Scope an id and extra fields to a block, restoring them afterwards.
+
+    Use one per unit of work so a long-running worker does not carry the previous
+    job's context into the next one:
+
+        with correlation(event_id=str(event_id)) as cid:
+            process(event_id)
+    """
+    cid_token = _correlation_id.set(value or new_id())
+    extra_token = _extra.set({**(_extra.get() or {}), **fields})
+    try:
+        yield _correlation_id.get()
+    finally:
+        _correlation_id.reset(cid_token)
+        _extra.reset(extra_token)

tmcommon/exceptions.py

@@ -0,0 +1,96 @@
+"""HTTP-shaped exceptions with a stable wire format.
+
+Kept dependency-free on purpose: the Flask adapter injects the request id, so
+these are usable from a scraper or a migration with no web framework present.
+"""
+
+from typing import Any, Optional
+
+__all__ = [
+    'BaseAPIException',
+    'BadRequest',
+    'Unauthorized',
+    'ValidationError',
+    'Forbidden',
+    'NotFound',
+    'Conflict',
+    'RateLimitExceeded',
+    'InternalServerError',
+    'ServiceUnavailable',
+]
+
+
+class BaseAPIException(Exception):
+    def __init__(
+        self,
+        message: str,
+        status_code: int,
+        error_type: Optional[str] = None,
+        details: Any = None,
+    ):
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.error_type = error_type or self.__class__.__name__
+        self.details = details
+
+    def to_dict(self, request_id: Optional[str] = None) -> dict:
+        error_dict = {
+            'error': {
+                'type': self.error_type,
+                'message': self.message,
+            },
+            'status': self.status_code,
+        }
+
+        if self.details is not None:
+            error_dict['error']['details'] = self.details
+        if request_id is not None:
+            error_dict['error']['request_id'] = request_id
+
+        return error_dict
+
+
+class BadRequest(BaseAPIException):
+    def __init__(self, message='Invalid request', details=None):
+        super().__init__(message, 400, 'BadRequest', details)
+
+
+class Unauthorized(BaseAPIException):
+    def __init__(self, message='Authentication required', details=None):
+        super().__init__(message, 401, 'Unauthorized', details)
+
+
+class ValidationError(BaseAPIException):
+    def __init__(self, message='Validation error', details=None):
+        super().__init__(message, 400, 'ValidationError', details)
+
+
+class Forbidden(BaseAPIException):
+    def __init__(self, message='Permission denied', details=None):
+        super().__init__(message, 403, 'Forbidden', details)
+
+
+class NotFound(BaseAPIException):
+    def __init__(self, message='Resource not found', details=None):
+        super().__init__(message, 404, 'NotFound', details)
+
+
+class Conflict(BaseAPIException):
+    def __init__(self, message='Resource conflict', details=None):
+        super().__init__(message, 409, 'Conflict', details)
+
+
+class RateLimitExceeded(BaseAPIException):
+    def __init__(self, message='Rate limit exceeded', details=None):
+        super().__init__(message, 429, 'RateLimitExceeded', details)
+
+
+class InternalServerError(BaseAPIException):
+    def __init__(self, message='Internal server error', details=None):
+        super().__init__(message, 500, 'InternalServerError', details)
+
+
+class ServiceUnavailable(BaseAPIException):
+    def __init__(self, message='Service temporarily unavailable', details=None):
+        super().__init__(message, 503, 'ServiceUnavailable', details)