API Reference

API Reference#

This section contains the API reference documentation for Gator.

REST API#

Gator provides a REST API for managing conda environments and packages. The API specification is available in the OpenAPI/Swagger format:

REST API Specification

Python API#

Environment Manager#

class mamba_gator.envmanager.EnvManager(root_dir: str, kernel_spec_manager: KernelSpecManager)#

Bases: object

Handles environment and package actions.

async check_update(env: str, packages: List[str]) → Dict[str, List[Dict[str, str]]]#

Check for packages update in an environment.

if ‘–all’ is the only element in packages, search for all possible update in the given environment.

Args:: env (str): Environment name packages (List[str]): List of packages to search for update
Returns:: {“updates”: List[package]}

async clone_env(env: str, name: str) → Dict[str, str]#

Clone an environment.

Args:: env (str): To-be-cloned environment name name (str): New environment name
Returns:: Dict[str, str]: Clone command output.

async conda_config() → Dict[str, Any]#

Get conda configuration.

Returns:: Dict[str, Any]: Conda configuration

async create_env(env: str, *args) → Dict[str, str]#

Create a environment from a list of packages.

Args:: env (str): Name of the environment *args (List[str]): optional, packages to install
Returns:: Dict[str, str]: Create command output

async delete_env(env: str) → Dict[str, str]#

Delete an environment.

Args:: env (str): Environment name
Returns:: Dict[str, str]: Deletion command output

async develop_packages(env: str, packages: List[str]) → Dict[str, List[Dict[str, str]]]#

Install packages in pip editable mode in an environment.

Args:: env (str): Environment name packages (List[str]): List of packages to install
Returns:: Dict[str, str]: Install command output.

async dry_run_preview(env: str, action: Literal['install', 'remove', 'update'], packages: List[str]) → Dict[str, Any]#: Preview solver actions for install, remove, or update (conda/mamba –dry-run).

async env_channels(configuration: Dict[str, Any] | None = None) → Dict[str, Dict[str, List[str]]]#

List available channels.

Args:: configuration (Dict[str, Any] or None): Conda configuration
Returns:: {“channels”: {<channel>: <uri>}}

async env_packages(env: str) → Dict[str, List[str]]#

List environment package.

Args:: env (str): Environment name
Returns:: {“packages”: List[package]}

async export_env(env: str, from_history: bool = False) → str | Dict[str, str]#

Export an environment as YAML file.

Args:: env (str): Environment name from_history (bool): If True, use –from-history option; default False
Returns:: str: YAML file content

async import_env(env: str, file_content: str, file_name: str = 'environment.txt') → Dict[str, str]#

Create an environment from a file.

Args:: env (str): Environment name file_content (str): File content file_name (str): optional, Original filename
Returns:: Dict[str, str]: Create command output

async info() → Dict[str, Any]#

Returns conda info –json execution.

Returns:: The dictionary of conda information

async install_packages(env: str, packages: List[str]) → Dict[str, str]#

Install packages in an environment.

Args:: env (str): Environment name packages (List[str]): List of packages to install
Returns:: Dict[str, str]: Install command output.

is_mamba()#

async list_available() → Dict[str, List[Dict[str, str]]]#

List all available packages

Returns:

{: “packages”: List[package], “with_description”: bool # Whether we succeed in get some channeldata.json files

}

async list_envs(whitelist: bool = False) → Dict[str, List[Dict[str, str | bool]]]#

List all environments that conda knows about.

Args:

whitelist (bool): optional, filter the environment list to respect: KernelSpecManager.whitelist (default: False)

An environment is described by a dictionary: {

name (str): environment name, dir (str): environment prefix, is_default (bool): is the root environment

}

Returns:: {“environments”: List[env]}: The environments

property log: Logger#: logging.Logger : Extension logger

property manager: str#

Conda package manager name.

For now, use mamba if it is installed. Otherwise, fallback to conda.

Returns:: str: Package manager

async package_search(q: str) → Dict[str, List]#

Search packages.

Args:

q (str): Search query

Returns:

{: “packages”: List[package], “with_description”: bool # Whether we succeed in get some channeldata.json files

}

async pkg_depends(pkg: str) → Dict[str, List[str]]#

List environment packages dependencies.

Args:: pkg (str): Package name
Returns:: {“package”: List[dependencies]}

async remove_packages(env: str, packages: List[str]) → Dict[str, str]#

Delete packages in an environment.

Args:: env (str): Environment name packages (List[str]): List of packages to delete
Returns:: Dict[str, str]: Delete command output.

async update_env(env: str, file_content: str, file_name: str = 'environment.yml') → Dict[str, str]#

Update a environment from a file.

Args:: env (str): Name of the environment file_content (str): File content file_name (str): optional, Original filename
Returns:: Dict[str, str]: Update command output

async update_packages(env: str, packages: List[str]) → Dict[str, str]#

Update packages in an environment.

Args:: env (str): Environment name packages (List[str]): List of packages to update
Returns:: Dict[str, str]: Update command output.

mamba_gator.envmanager.get_env_path(kernel_spec: Dict[str, Any]) → str | None#

Get the conda environment path.

Args:: kernel_spec (dict): Kernel spec
Returns:: str: Best guess for the environment path

mamba_gator.envmanager.normalize_name(name: str) → str#: Normalize package name listing for comparison between conda and pip.

mamba_gator.envmanager.normalize_pkg_info(s: Dict[str, Any]) → Dict[str, str | List[str]]#

Normalize package information.

Args:: s (dict): Raw package information
Returns:: dict: Normalized package information

mamba_gator.envmanager.normalize_preview_pkg(s: Dict[str, Any]) → Dict[str, Any]#: Normalize a LINK/UNLINK/FETCH record from conda –dry-run JSON for the UI.

mamba_gator.envmanager.parse_version(version: str) → Version | None#: Handle R-style and year-based versions

Handlers#

class mamba_gator.handlers.ActionsStack#

Bases: object

Process long asynchronous task.

The task result can only be queried once.

Note: The task start immediately => may bring trouble if the user is not careful, this assumes ‘conda’ handle lockers when appropriate.

cancel(idx: int) → NoReturn#

Cancel the task idx.

Args:: idx (int): Task index

get(idx: int) → Any#

Get the task idx results or None.

Args:: idx (int): Task index
Returns:: Any: None if the task is pending else its result
Raises:: ValueError: If the task idx does not exists. asyncio.CancelledError: If the task idx was cancelled.

put(task: Callable, *args) → int#

Add a asynchronous task into the queue.

Args:: task (Callable): Asynchronous task *args : arguments of the task
Returns:: int: Task id

class mamba_gator.handlers.ChannelsHandler(application: Application, request: HTTPServerRequest, **kwargs: Any)#

Bases: EnvBaseHandler

Handle channels actions.

get()#: GET /channels list the channels.

class mamba_gator.handlers.EnvBaseHandler(application: Application, request: HTTPServerRequest, **kwargs: Any)#

Bases: APIHandler

Mixin for an env manager. Just maintains a reference to the ‘env_manager’ which implements all of the conda functions.

property env_manager: EnvManager#: EnvManager : Return our env_manager instance

property log: Logger#: logging.Logger: The extension logger

redirect_to_task(index: int)#: Close a request by redirecting to a task.

class mamba_gator.handlers.EnvironmentHandler(application: Application, request: HTTPServerRequest, **kwargs: Any)#

Bases: EnvBaseHandler

Environment handler.

delete(env: str)#: DELETE /environments/<env> deletes an environment.

get(env: str)#

GET /environments/<env> List or export the environment packages.

Query arguments:: status: “installed” (default) or “has_update” download: 0 (default) or 1 history: 0 (default) or 1

patch(env: str)#

PATCH /environments/<env> update an environment.

Request json body: {

file (str): optional, environment file (TXT or YAML format) filename (str): optional, environment filename of the file content

}

class mamba_gator.handlers.EnvironmentsHandler(application: Application, request: HTTPServerRequest, **kwargs: Any)#

Bases: EnvBaseHandler

Environments handler.

get()#

GET /environments which lists the environments.

Query arguments:: whitelist (int): optional flag 0 or 1 to respect KernelSpecManager.whitelist
Raises:: 500 if an error occurs

post()#

POST /environments creates an environment.

Method of creation depends on the request data (first find is used):

packages: Create from a list of packages
twin: Clone the environment given by its name
file: Import from the given file content

Request json body: {

name (str): environment name packages (List[str]): optional, list of packages to install twin (str): optional, environment name to clone file (str): optional, environment file (TXT or YAML format) filename (str): optional, environment filename of the file content

}

class mamba_gator.handlers.PackagesEnvironmentHandler(application: Application, request: HTTPServerRequest, **kwargs: Any)#

Bases: EnvBaseHandler

Handle actions on environment packages.

delete(env: str)#

DELETE /environments/<env>/packages delete some packages.

Request json body: {

packages (List[str]): list of packages to delete

}

patch(env: str)#

PATCH /environments/<env>/packages update some packages.

If no packages are provided, update all possible packages.

Request json body: {

packages (List[str]): optional, list of packages to update

}

post(env: str)#

POST /environments/<env>/packages install some packages.

Packages can be installed in development mode. In that case, the fullpath to the package directory should be provided.

Query arguments:: develop: 0 (default) or 1

Request json body: {

packages (List[str]): list of packages to install

}

class mamba_gator.handlers.PackagesHandler(application: Application, request: HTTPServerRequest, **kwargs: Any)#

Bases: EnvBaseHandler

Handles packages search

get()#

GET /packages Search for packages.

Query arguments:: dependencies: 0 (default) or 1 query (str): optional string query

class mamba_gator.handlers.PreviewPackagesEnvironmentHandler(application: Application, request: HTTPServerRequest, **kwargs: Any)#

Bases: EnvBaseHandler

Handle dry-run previews for environment package changes (install/remove/update).

patch(env: str)#

PATCH /environments/<env>/packages/preview preview solver actions.

Request json body: {

“action”: “install” | “remove” | “update”, “packages”: [“pkg”, “other=1.0”, …]

}

class mamba_gator.handlers.TaskHandler(application: Application, request: HTTPServerRequest, **kwargs: Any)#

Bases: EnvBaseHandler

Handler for /tasks/<id>

delete(index: int)#

DELETE /tasks/<id> cancels the task index.

Status are: * 204: Task cancelled

Args:: index (int): Task index
Raises:: 404 if task index does not exist

get(index: int)#

GET /tasks/<id> Returns the task index status.

Status are:

200: Task result is returned
202: Task is pending
500: Task ends with errors

Args:: index (int): Task index
Raises:: 404 if task index does not exist

TypeScript/JavaScript API#

The TypeScript/JavaScript API documentation will be available in a future release.

JupyterLab Extension#

The JupyterLab extension provides the following main interfaces:

IEnvironmentManager: Interface for managing conda environments
Conda.IPackageManager: Interface for managing conda packages

Detailed TypeScript API documentation coming soon.

API Reference

Contents

API Reference#

REST API#

Python API#

Environment Manager#

Handlers#

TypeScript/JavaScript API#

JupyterLab Extension#