Skip to content

Coding Conventions

TODO: update

DO NOT FORGET TESTS

Most style are enforced with the pre-commit hooks which automatically reformat the code and sort the imports. Code should follow PEP-8, particularly for naming conventions as these aren't modified by the pre-commit hooks.

Module Specifications

Depending on which module you are using, there could be rules to follow that are listed below.

Module Do Do not
`pytest` 
import pytest


@pytest.fixture
def my_ficture():
    ...

from pytest import fixture


@fixture
def my_ficture():
    ...
`datetime` 
from datetime import datetime, timedelta, timezone

delay = datetime.now(tz=timezone.utc) + timedelta(hours=1)

import datetime

delay = datetime.datetime.now() + datetime.timedelta(hours=1)
`SQL Alchemy` 
class Owners(Base):
    __tablename__ = "Owners"
    owner_id: Mapped[int] = mapped_column(
        "OwnerID", Integer, primary_key=True, autoincrement=True
    )
    creation_time: Mapped[datetime_now] = mapped_column("CreationTime")
    name: Mapped[str255] = mapped_column("Name")

class Owners(Base):
    __tablename__ = "Owners"
    OwnerID: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
    CreationTime: Mapped[datetime_now]
    Name: Mapped[str255]

Structure

The following structures principles may also be followed:

  • __init__.py should not contain code, but __all__ as a list
  • At a package level (routers for example) we have as few files as possible
  • The package level __init__.py should contain an empty __all__ and the modules at that level should expose their respective public API
  • If the files have much in common (think of jobs, which have the sandbox, the joblogging, etc), we put them in a subpackage (e.g routers.job). The code goes in a specific file (job.py, joblogging.py)
  • At subpackage level, __init__.py should expose the public API through the __all__ list by importing from the modules at that level. These submodules should not contain an __all__

See this issue.

Architecture

To make sure that each part of DiracX is doing only what it is supposed to do, you also need to follow these instructions:

  • diracx-routers should deal with user interactions through HTTPs. It is expected to deal with permissions and should call diracx-logic. Results returned should be translated into HTTP responses.
  • diracx-logic should embed Dirac specificities. It should encapsulate the logic of the services and should call diracx-db to interact with databases.
  • diracx-db should contain atomic methods (complex logic is expected to be located in diracx-db).

Error handling boundaries

  • diracx-db and diracx-logic should raise domain exceptions (typically DiracError subclasses), and should not depend on fastapi.
  • diracx-routers is the HTTP boundary and should translate known backend/domain exceptions into HTTPException with the desired status code, message, and headers.
  • DiracError handling registered at app level (see diracx-routers/src/diracx/routers/factory.py, especially app.add_exception_handler(DiracError, cast(handler_signature, dirac_error_handler))) is a fallback safety net for uncaught domain exceptions, not a replacement for explicit mapping when the router needs specific HTTP behavior.
  • Protocol-specific responses can be handled directly in routers when HTTPException shape is not suitable (for example OAuth2-style payloads in tokens.py), e.g. by returning a JSONResponse directly.