satcat.sdk package#

Subpackages#

Submodules#

class satcat.sdk.client.Client(default_page_size=32)#

Bases: object

Base Client class which may be used to make requests to Satcat APIs. May be used as a context manager with the with keyword:

with Client() as client:
    client.request(...)

If not used with the with keyword, it is recommended to explicitly close the Client with client.close() after the application is finished making requests.

Parameters:: default_page_size (int) – Default page size to use when sending repeated listing requests to a collection endpoint, defaults to 10

authenticate_session(timeout_s=None)#

Authenticate the HTTP session with the authentication provider using the: authentication method determined by satcat.sdk.settings.auth_method .

This is done automatically when using request_authenticated .

close()#: Close the client and any associated network connections.

property cola_maneuvers: ColaManeuverClient#: Library containing SDK functions for interacting with the Satcat COLA Maneuver Designer API.

create_ephemeris(*args, **kwargs)#: Alias for client.screening.create_ephemeris.

download_ephemeris(*args, **kwargs)#: Alias for client.screening.download_ephemeris.

property events: EventClient#: Library containing SDK functions for interacting with the Satcat Events API.

get_ephemeris(*args, **kwargs)#: Alias for client.screening.get_ephemeris.

list_ephemerides(*args, **kwargs)#: Alias for client.screening.list_ephemerides.

property od: ODClient#: Library containing SDK functions for interacting with the Satcat OD API.

operationalize_ephemeris(*args, **kwargs)#: Alias for client.screening.operationalize_ephemeris.

ping_authenticated()#

Sends a request to Kayhan servers to confirm a healthy and authenticated session. Returns True if valid, raises an HTTPError if not.

Return type:: bool

property propagation: PropagationClient#: Library containing SDK functions for interacting with the Satcat Propagation API.

request(path, method='GET', data=None, json=None, params=None, files=None, api='rest')#

Make an HTTP request to a Satcat API. .. warning:: For most use cases, this function should only be called internally by high level functions inside the SDK, such as those inside client.screening .

Return type:: Response

request_authenticated(path, method='GET', data=None, json=None, params=None, ignore_failure=False, files=None, api='rest')#

Return type:: Response

Ensure that the HTTP session is authorized and make an HTTP request to: a Satcat API.

Warning

For most use cases, this function should only be called internally by high level functions inside the SDK, such as those inside client.screening .

request_list(path, filters=None, count=None, params=None, sort_direction=SortDirection.DESC, sort_field='created_at', fields=None)#

Return type:: Collection[Any]

Request a list of resources from a Satcat API and automatically page through: the results if necessary.

Warning

For most use cases, this function should only be called internally by high level functions inside the SDK, such as those inside client.screening .

property screening: ScreeningClient#: Library containing SDK functions for interacting with the Satcat Screening API.

session: Session#

satcat.sdk.client.check_version()#

satcat.sdk.client.get_latest_version(package_name)#

Return type:: str

class satcat.sdk.models.Model(**data)#

Bases: BaseModel

Create a new model by parsing and validating input data from keyword arguments.

Raises ValidationError if the input data cannot be parsed to form a valid model.

class Config#

Bases: object

arbitrary_types_allowed: bool = True#

fields = {'client': {'exclude': Ellipsis}}#

json_encoders = {<class 'datetime.datetime'>: <function <lambda>>}#

orm_mode: bool = True#

class satcat.sdk.od_client.ODClient(client)#

Bases: object

client: Client#

download_file(object_id, filename, output_path)#

Download an orbital determination (OD) file for a specific object.

Parameters:

object_id (int) – The NORAD ID or temporary ID of the object that this OD file describes.
filename (str) – The name of the file to download.
output_path (Optional[PathLike]) – Optional path to save the downloaded file. If None, the file content is returned as bytes.

Returns:

The content of the downloaded file as bytes.

Return type:

bytes

download_recent_files(object_id, number=1, report=False, output_dir=None)#

Download the most recent orbital determination (OD) files for a specific object.

Parameters:

object_id (int) – The NORAD ID or temporary ID of the object that this OD file describes.
number (int) – The number of recent files to download.
report (bool) – If True, downloads the most recent pdf report file as well
output_dir (Optional[PathLike]) – Optional directory to save the downloaded files. If None, files are saved to the current working directory.

Returns:

A tuple containing the count of definitive files, predictive files, and a boolean indicating if a PDF report was downloaded.

Return type:

Tuple[int, int, bool]

list_assets()#

List assets for which the user has orbital determination data available.

:return The list of object IDs. :rtype: Collection[int]

list_object_files(object_id, today=False, results=False)#

List orbital determination files for a specific object.

Parameters:

object_id (int) – The NORAD ID or temporary ID of the object.
today (bool) – If True, only list files uploaded today.
results (bool) – If True, only list result files.

Returns:

The list of files for the specified object.

Return type:

Collection[Dict[str, Any]]

upload_file(object_id, path_or_buf, filename=None)#

Upload an orbital determination (OD) file for a specific object.

The file content can be provided either as a filesystem path or as an already-open file-like object. A filename must either be provided explicitly or derivable from path_or_buf; otherwise this method will raise a ValueError.

Parameters:

object_id (int) – The NORAD ID or temporary ID of the object that this OD file describes.
path_or_buf (Union[PathLike, TextIO, StringIO]) – Path to a file on disk, or an open text file-like object (e.g. io.StringIO) containing the OD data to upload.
filename (Optional[str]) –
Optional explicit filename to send to the API. If not provided, the filename will be derived from path_or_buf when possible (e.g. using os.path.basename). The filename must follow one of these patterns:
```
gnss_<object_id>_YYYY_MM_DD_HH_MM_SSZ.(json|csv|navsol)
gnss_<object_id>_YYYY-MM-DDTHH:MM:SSZ.(json|csv|navsol)
maneuver_<object_id>_YYYY_MM_DD_HH_MM_SSZ.(opm|txt)
maneuver_<object_id>_YYYY-MM-DDTHH:MM:SSZ.(opm|txt)
```
If no filename can be determined, a ValueError is raised.

Returns:

The JSON response from the OD upload endpoint.

Return type:

Dict[str, Any]

class satcat.sdk.settings.CLISettings(**data)#

Bases: BaseModel

Create a new model by parsing and validating input data from keyword arguments.

Raises ValidationError if the input data cannot be parsed to form a valid model.

is_cli: bool#

output_format: OutputFormat#

show_progress: bool#

class satcat.sdk.settings.OutputFormat(value)#

Bases: str, Enum

An enumeration.

JSON = 'json'#

RICH = 'rich'#

class satcat.sdk.settings.Settings(_env_file='<object object>', _env_file_encoding=None, _env_nested_delimiter=None, _secrets_dir=None, **values)#

Bases: BaseSettings

Create a new model by parsing and validating input data from keyword arguments.

Raises ValidationError if the input data cannot be parsed to form a valid model.

class Config#

Bases: object

classmethod customise_sources(init_settings, env_settings, file_secret_settings)#

env_file_encoding = 'utf-8'#

env_prefix = 'satcat_'#

extra = 'allow'#

auth_client_id: Optional[str]#

auth_client_secret: Optional[str]#

auth_method: Literal['password', 'client_credentials']#

auth_password: Optional[str]#

auth_url: AnyUrl#

auth_username: Optional[str]#

cli: CLISettings#

default_timeout: int#

satcat_base_url: AnyUrl#

classmethod satcat_base_url_must_end_with_slash(v)#

property satcat_rest_api_url: str#

satcat_rest_api_url_override: Optional[AnyUrl]#

property satcat_web_api_url: str#

satcat_web_api_url_override: Optional[AnyUrl]#

satcat.sdk.settings.json_config_settings_source(settings)#

A simple settings source that loads variables from a JSON file at the project’s root.

Here we happen to choose to use the env_file_encoding from Config when reading config.json

Return type:: Dict[str, Any]

satcat.sdk.settings.load_settings_file(config_path)#

exception satcat.sdk.utils.NotFoundError#: Bases: Exception

class satcat.sdk.utils.SortDirection(value)#

Bases: Enum

An enumeration.

ASC = 'asc'#

DESC = 'desc'#

satcat.sdk.utils.kebab_case(text)#

Return type:: str

class satcat.sdk.utils.open_path_or_buf(path_or_buf, mode='r')#

Bases: object

buf: IO#

need_to_close_buf: bool = False#

path_or_buf: Union[Path, IO]#

satcat.sdk.utils.poll_job_for_completion(get_job_fn, poll_interval=5, timeout=3600, created_timeout=30)#

satcat.sdk.utils.poll_job_for_completion_percent_generator(get_job_fn, poll_interval=5, timeout=3600)#

satcat.sdk.utils.remove_none_vals(d)#

Return type:: Dict

satcat.sdk.utils.utc(timestamp)#

Create a datetime object from an ISO8601 timestamp string. The timestamp string must include the “Z” suffix indicating that the timestamp is expressed in the UTC time system.

It is recommended that you use this function to pass any datetime parameters to Satcat SDK functions to ensure that your datetime is created with the correct timezone information.

Parameters:: timestamp (str) – The timestamp string to convert
Returns:: The created datetime object
Return type:: datetime