centraldogma package

centraldogma.dogma module

class centraldogma.dogma.Dogma(base_url: str | None = None, token: str | None = None, **configs)

Bases: object

DEFAULT_BASE_URL = 'http://localhost:36462'

DEFAULT_TOKEN = 'anonymous'

create_project(name: str) → Project

Creates a project. The creator of the project will become the owner of the project.

create_repository(project_name: str, name: str) → Repository

Creates a repository. Only the owner and an admin can create.

file_watcher(project_name: str, repo_name: str, query: ~centraldogma.query.Query[~centraldogma.dogma.T], function: ~typing.Callable[[~centraldogma.dogma.T], ~centraldogma.dogma.U] = <function Dogma.<lambda>>) → Watcher[U]

Returns a Watcher which notifies its listeners after applying the specified function when the result of the given Query becomes available or changes. e.g:

with dogma.file_watcher("foo_project", "bar_repo", Query.json("/baz.json"),
                        lambda content: MyType.from_dict(content)) as watcher:
    def listener(revision: Revision, value: MyType) -> None:
        ...

    watcher.watch(listener)

Parameters:

• query – the query to watch a file or a content in the repository.

• function – the function to convert the given content into another.

get_file(project_name: str, repo_name: str, file_path: str, revision: int | None = None, json_path: str | None = None) → Content

Gets a file. The user should have read permission at least.

Parameters:

• revision – The revision of the file to get. If not specified, gets the file of the latest revision.

• json_path – The JSON path expressions.

get_files(project_name: str, repo_name: str, path_pattern: str | None = None, revision: int | None = None) → List[Content]

Gets files. The user should have read permission at least. The difference from the API List files is that this includes the content of the files.

Parameters:

• path_pattern – A path pattern is a variant of glob as follows.
  “/**” - find all files recursively
  “*.json” - find all JSON files recursively
  “/foo/*.json” - find all JSON files under the directory /foo
  “/*/foo.txt” - find all files named foo.txt at the second depth level
  “*.json,/bar/*.txt” - use comma to match any patterns
  This will bring all of the files in the repository, if unspecified.

• revision – The revision of the list to get. If not specified, gets the list of the latest revision.

list_files(project_name: str, repo_name: str, path_pattern: str | None = None, revision: int | None = None) → List[Content]

Lists files. The user should have read permission at least.

Parameters:

• path_pattern – A path pattern is a variant of glob as follows.
  “/**” - find all files recursively
  “*.json” - find all JSON files recursively
  “/foo/*.json” - find all JSON files under the directory /foo
  “/*/foo.txt” - find all files named foo.txt at the second depth level
  “*.json,/bar/*.txt” - use comma to match any patterns
  This will bring all of the files in the repository, if unspecified.

• revision – The revision of the list to get. If not specified, gets the list of the latest revision.

list_projects(removed: bool = False) → List[Project]

Lists all projects, in the order that they were created on the Central Dogma server.

list_repositories(project_name: str, removed: bool = False) → List[Repository]

Lists all repositories, in the order that they were created on the Central Dogma server.

merge_files(project_name: str, repo_name: str, merge_sources: List[MergeSource], json_paths: List[str] | None = None, revision: int | None = None) → MergedEntry

Returns the merged result of files represented by MergeSource. Each MergeSource can be optional, indicating that no error should be thrown even if the path doesn’t exist. If json_paths is specified, each json_path is applied recursively on the merged result. If any of the json_path s is invalid, a QueryExecutionException is thrown.

Raises:

ValueError – If the provided merge_sources is empty.

Returns:

the MergedEntry which contains the merged content for the given query.

normalize_repository_revision(project_name: str, name: str, revision: int) → int

Normalizes the revision into an absolute revision.

purge_project(name: str) → None

Purges a project. Only the owner and an admin can purge the project removed before.

purge_repository(project_name: str, name: str) → None

Purges a repository. Only the owner and an admin can purge a repository removed before.

push(project_name: str, repo_name: str, commit: Commit, changes: List[Change]) → PushResult

Creates, replaces, renames or deletes files. The user should have a permission to write.

Parameters:

• commit – A commit message for changes.

• changes – Detailed changes including path, type and content. If the type is REMOVE, the content should be empty. If the type is RENAME, the content is supposed to be the new name.

remove_project(name: str) → None

Removes a project. Only the owner and an admin can remove the project.

remove_repository(project_name: str, name: str) → None

Removes a repository. Only the owner and an admin can remove.

repository_watcher(project_name: str, repo_name: str, path_pattern: str, function: ~typing.Callable[[~centraldogma.data.revision.Revision], ~centraldogma.dogma.T] = <function Dogma.<lambda>>, timeout_millis: int = 60000) → Watcher[T]

Returns a Watcher which notifies its listeners when the specified repository has a new commit that contains the changes for the files matched by the given path_pattern. e.g:

def get_files(revision: Revision) -> List[Content]:
    return dogma.get_files("foo_project", "bar_repo", revision, "/*.json")

with dogma.repository_watcher("foo_project", "bar_repo", "/*.json", get_files) as watcher:
    def listener(revision: Revision, contents: List[Content]) -> None:
        ...

    watcher.watch(listener)

Note that you may get RevisionNotFoundException during the get_files() call and may have to retry in the above example due to a known issue.

Parameters:

• path_pattern – the path pattern to match files in the repository.

• function – the function to convert the given Revision into another.

• timeout_millis – the timeout millis for the watching request.

unremove_project(name: str) → Project

Unremoves a project which is removed before. Only an admin can unremove the project.

unremove_repository(project_name: str, name: str) → Repository

Unremoves a repository. Only the owner and an admin can unremove.

watch_file(project_name: str, repo_name: str, last_known_revision: Revision, query: Query[T], timeout_millis: int = 60000) → Entry[T] | None

Waits for the file matched by the specified Query to be changed since the specified last_known_revision. If no changes were made within the specified timeout_millis, None will be returned. It is recommended to specify the largest timeout_millis allowed by the server. If unsure, use the default watch timeout.

Returns:

the Entry which contains the latest known Query result. None if the file was not changed for timeout_millis milliseconds since the invocation of this method.

watch_repository(project_name: str, repo_name: str, last_known_revision: Revision, path_pattern: str, timeout_millis: int = 60000) → Revision | None

Waits for the files matched by the specified path_pattern to be changed since the specified last_known_revision. If no changes were made within the specified timeout_millis, None will be returned. It is recommended to specify the largest timeout_millis allowed by the server. If unsure, use the default watch timeout.

Returns:

the latest known Revision which contains the changes for the matched files. None if the files were not changed for timeout_millis milliseconds since the invocation of this method.

centraldogma.project_service module

class centraldogma.project_service.ProjectService(client: BaseClient)

Bases: object

create(name: str) → Project

list(removed: bool) → List[Project]

purge(name: str) → None

remove(name: str) → None

unremove(name: str) → Project

centraldogma.repository_service module

class centraldogma.repository_service.RepositoryService(client: BaseClient)

Bases: object

create(project_name: str, name: str) → Repository

list(project_name: str, removed: bool) → List[Repository]

normalize_revision(project_name: str, name: str, revision: int) → int

purge(project_name: str, name: str) → None

remove(project_name: str, name: str) → None

unremove(project_name: str, name: str) → Repository

centraldogma.content_service module

class centraldogma.content_service.ContentService(client: BaseClient)

Bases: object

get_file(project_name: str, repo_name: str, file_path: str, revision: int | None, json_path: str | None) → Content

get_files(project_name: str, repo_name: str, path_pattern: str | None, revision: int | None, include_content: bool = False) → List[Content]

merge_files(project_name: str, repo_name: str, merge_sources: List[MergeSource], json_paths: List[str] | None, revision: int | None) → MergedEntry

push(project_name: str, repo_name: str, commit: Commit, changes: List[Change]) → PushResult

watch_file(project_name: str, repo_name: str, last_known_revision: Revision, query: Query[T], timeout_millis: int) → Entry[T] | None

watch_repository(project_name: str, repo_name: str, last_known_revision: Revision, path_pattern: str, timeout_millis: int) → Revision | None

centraldogma.watcher module

class centraldogma.watcher.Latest(revision: Revision, value: T)

Bases: Generic[T]

A holder of the latest known value and its Revision retrieved by Watcher.

revision: Revision

value: T

class centraldogma.watcher.Watcher

Bases: Generic[T]

Watches the changes of a repository or a file.

await_initial_value() → Latest[T]

Waits for the initial value to be available.

close() → None

Stops watching the file specified in the Query or the path pattern in the repository.

initial_value_future() → Future

Returns the Future which completes a Latest[T] when the initial value retrieval is done successfully.

latest() → Latest[T]

Returns the latest Revision and value of watch_file() result.

watch(listener: Callable[[Revision, T], None]) → None

Registers a listener that will be invoked when the value of the watched entry becomes available or changes.

centraldogma.query module

class centraldogma.query.Query(path: str, query_type: ~centraldogma.query.QueryType, expressions: ~typing.List[str] = <factory>)

Bases: Generic[T]

A query on a file.

expressions: List[str]

static identity(path: str) → Query[str]

Returns a newly-created Query that retrieves the content as it is.

Parameters:

path – the path of a file being queried on

static json(path: str) → Query[Any]

Returns a newly-created Query that retrieves the JSON content as it is.

Parameters:

path – the path of a file being queried on

static json_path(path: str, json_paths: List[str]) → Query[Any]

Returns a newly-created Query that applies a series of JSON path expressions to the content.

Parameters:

• path – the path of a file being queried on

• json_paths – the JSON path expressions to apply

path: str

query_type: QueryType

static text(path: str) → Query[str]

Returns a newly-created Query that retrieves the textual content as it is.

Parameters:

path – the path of a file being queried on

class centraldogma.query.QueryType(value)

Bases: Enum

An enumeration.

IDENTITY = 'IDENTITY'

IDENTITY_JSON = 'IDENTITY_JSON'

IDENTITY_TEXT = 'IDENTITY_TEXT'

JSON_PATH = 'JSON_PATH'

centraldogma.exceptions module

exception centraldogma.exceptions.AuthorizationException

Bases: CentralDogmaException

A CentralDogmaException that is raised when a client failed to authenticate or attempted to perform an unauthorized operation.

exception centraldogma.exceptions.BadRequestException

Bases: CentralDogmaException

An exception indicating a 400 Bad Client Request.

exception centraldogma.exceptions.CentralDogmaException

Bases: Exception

An exception that is raised when failed to access Central Dogma.

exception centraldogma.exceptions.ChangeConflictException

Bases: CentralDogmaException

A CentralDogmaException that is raised when attempted to push a commit which cannot be applied without a conflict.

exception centraldogma.exceptions.EntryNoContentException

Bases: CentralDogmaException

A CentralDogmaException that is raised when attempted to retrieve the content from a directory entry.

exception centraldogma.exceptions.EntryNotFoundException

Bases: CentralDogmaException

A CentralDogmaException that is raised when attempted to access a non-existent entry in a repository.

exception centraldogma.exceptions.ForbiddenException

Bases: CentralDogmaException

An exception indicating that an access to a resource requested by a client has been forbidden by the Central Dogma.

exception centraldogma.exceptions.InvalidResponseException

Bases: CentralDogmaException

A CentralDogmaException that is raised when a client received an invalid response.

exception centraldogma.exceptions.NotFoundException

Bases: CentralDogmaException

An exception indicating a 404 Not Found.

exception centraldogma.exceptions.ProjectExistsException

Bases: CentralDogmaException

A CentralDogmaException that is raised when attempted to create a project with an existing project name.

exception centraldogma.exceptions.ProjectNotFoundException

Bases: CentralDogmaException

A CentralDogmaException that is raised when attempted to access a non-existent project.

exception centraldogma.exceptions.QueryExecutionException

Bases: CentralDogmaException

A CentralDogmaException that is raised when the evaluation of a Query has failed.

exception centraldogma.exceptions.RedundantChangeException

Bases: CentralDogmaException

A CentralDogmaException that is raised when attempted to push a commit without effective changes.

exception centraldogma.exceptions.RepositoryExistsException

Bases: CentralDogmaException

A CentralDogmaException that is raised when attempted to create a repository with an existing repository name.

exception centraldogma.exceptions.RepositoryNotFoundException

Bases: CentralDogmaException

A CentralDogmaException that is raised when attempted to access a non-existent repository.

exception centraldogma.exceptions.RevisionNotFoundException

Bases: CentralDogmaException

A CentralDogmaException that is raised when attempted to access a non-existent revision.

exception centraldogma.exceptions.ShuttingDownException

Bases: CentralDogmaException

A CentralDogmaException that is raised when Central Dogma cannot handle a request because it’s shutting down.

exception centraldogma.exceptions.UnauthorizedException

Bases: CentralDogmaException

An exception indicating a 401 Unauthorized.

exception centraldogma.exceptions.UnknownException

Bases: CentralDogmaException

An exception used for reporting unknown exceptions.

centraldogma.exceptions.to_exception(response: Response) → CentralDogmaException

Subpackages

• centraldogma.data package
  • Submodules
  • centraldogma.data.change module
    • Change
      • Change.content
      • Change.from_dict()
      • Change.from_json()
      • Change.path
      • Change.schema()
      • Change.to_dict()
      • Change.to_json()
      • Change.type
    • ChangeType
      • ChangeType.APPLY_JSON_PATCH
      • ChangeType.APPLY_TEXT_PATCH
      • ChangeType.REMOVE
      • ChangeType.RENAME
      • ChangeType.UPSERT_JSON
      • ChangeType.UPSERT_TEXT
  • centraldogma.data.commit module
    • Commit
      • Commit.detail
      • Commit.from_dict()
      • Commit.from_json()
      • Commit.markup
      • Commit.schema()
      • Commit.summary
      • Commit.to_dict()
      • Commit.to_json()
  • centraldogma.data.content module
    • Content
      • Content.content
      • Content.from_dict()
      • Content.from_json()
      • Content.path
      • Content.revision
      • Content.schema()
      • Content.to_dict()
      • Content.to_json()
      • Content.type
      • Content.url
  • centraldogma.data.creator module
    • Creator
      • Creator.email
      • Creator.from_dict()
      • Creator.from_json()
      • Creator.name
      • Creator.schema()
      • Creator.to_dict()
      • Creator.to_json()
  • centraldogma.data.entry module
    • Entry
      • Entry.content
      • Entry.content_as_text()
      • Entry.directory()
      • Entry.has_content()
      • Entry.json()
      • Entry.text()
    • EntryType
      • EntryType.DIRECTORY
      • EntryType.JSON
      • EntryType.TEXT
  • centraldogma.data.merge_source module
    • MergeSource
      • MergeSource.optional
      • MergeSource.path
  • centraldogma.data.merged_entry module
    • MergedEntry
      • MergedEntry.content
      • MergedEntry.from_dict()
  • centraldogma.data.project module
    • Project
      • Project.created_at
      • Project.creator
      • Project.dataclass_json_config
      • Project.from_dict()
      • Project.from_json()
      • Project.name
      • Project.schema()
      • Project.to_dict()
      • Project.to_json()
      • Project.url
  • centraldogma.data.push_result module
    • PushResult
      • PushResult.dataclass_json_config
      • PushResult.from_dict()
      • PushResult.from_json()
      • PushResult.pushed_at
      • PushResult.revision
      • PushResult.schema()
      • PushResult.to_dict()
      • PushResult.to_json()
  • centraldogma.data.repository module
    • Repository
      • Repository.created_at
      • Repository.creator
      • Repository.dataclass_json_config
      • Repository.from_dict()
      • Repository.from_json()
      • Repository.head_revision
      • Repository.name
      • Repository.schema()
      • Repository.to_dict()
      • Repository.to_json()
      • Repository.url
  • centraldogma.data.revision module
    • Revision
      • Revision.head()
      • Revision.init()
      • Revision.major