Skip to content

capturegraph.api_models.paths #

CaptureGraph API Path Models#

Pydantic models for representing file and directory paths in the CaptureGraph API. These models are shared between capturegraph-server and capturegraph-sync.

PathComponent #

Bases: BaseModel

A single component in a file path, optionally with a session ID.

When session_id is present, the path component represents a session folder whose name is the hex-encoded session ID (e.g., "000647C309C2723B").

Source code in capturegraph-lib/capturegraph/api_models/paths.py 
12
13
14
15
16
17
18
19
20
class PathComponent(BaseModel):
    """A single component in a file path, optionally with a session ID.

    When session_id is present, the path component represents a session folder
    whose name is the hex-encoded session ID (e.g., "000647C309C2723B").
    """

    name: str
    session_id: int | None = None

FilePathModel #

Bases: BaseModel

Model for identifying a file on the server.

Represents the full path to a file including its location in the directory hierarchy, name, type, and possible extensions.

Source code in capturegraph-lib/capturegraph/api_models/paths.py 
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
class FilePathModel(BaseModel):
    """Model for identifying a file on the server.

    Represents the full path to a file including its location in the
    directory hierarchy, name, type, and possible extensions.
    """

    path: list[PathComponent]
    name: str
    type_name: str
    file_extensions: list[str]
    index: int | None = None
    user_id: str | None = None

    def to_filename(self) -> str:
        """Convert to just the filename (without path)."""
        name = f"{self.name}_{self.index}" if self.index is not None else self.name
        ext = self.file_extensions[0] if self.file_extensions else ""
        return f"{name}.{ext}" if ext else name

    def to_relative_path(self) -> str:
        """Convert to a relative file path string."""
        parts = []
        for component in self.path:
            parts.append(component.name)
            if component.session_id is not None:
                parts.append(f"{component.session_id:016X}")

        parts.append(self.to_filename())
        return "/".join(parts)

to_filename() #

Convert to just the filename (without path).

Source code in capturegraph-lib/capturegraph/api_models/paths.py 
37
38
39
40
41
def to_filename(self) -> str:
    """Convert to just the filename (without path)."""
    name = f"{self.name}_{self.index}" if self.index is not None else self.name
    ext = self.file_extensions[0] if self.file_extensions else ""
    return f"{name}.{ext}" if ext else name

to_relative_path() #

Convert to a relative file path string.

Source code in capturegraph-lib/capturegraph/api_models/paths.py 
43
44
45
46
47
48
49
50
51
52
def to_relative_path(self) -> str:
    """Convert to a relative file path string."""
    parts = []
    for component in self.path:
        parts.append(component.name)
        if component.session_id is not None:
            parts.append(f"{component.session_id:016X}")

    parts.append(self.to_filename())
    return "/".join(parts)

SessionPathModel #

Bases: BaseModel

Model for identifying a session folder on the server.

Source code in capturegraph-lib/capturegraph/api_models/paths.py 
55
56
57
58
59
class SessionPathModel(BaseModel):
    """Model for identifying a session folder on the server."""

    path: list[PathComponent]
    name: str

DirectoryPathModel #

Bases: BaseModel

Model for identifying a directory on the server.

Source code in capturegraph-lib/capturegraph/api_models/paths.py 
62
63
64
65
class DirectoryPathModel(BaseModel):
    """Model for identifying a directory on the server."""

    path: list[PathComponent]