sdss_brain Reference¶

Api¶

class sdss_brain.api.manager.ApiManager[source]¶

Bases: object

Class for managing SDSS APIs

This class provides an interface for handling and managing the selection of various SDSS APIs. It allows toggling of the current API to use for all remote requests.

Variables:

domains (dict) – A dictionary of available SDSS domains
apis (dict) – A dictionary of available SDSS APIs
profile (Type[ApiProfile]) – The currently selected API to use

display(value: str, pprint: bool = False, show_docs: bool = True, show_desc: bool = True, **kwargs) → Table[source]¶

Display the APIs or domains as an Astropy Table

Display the list of available SDSS APIs or domains as an Astropy Table.

Parameters:

value (str) – Either “api(s)” or “domain(s)”
pprint (bool, optional) – If True, pretty print the Astropy Table, by default False
show_docs (bool, optional) – If True, include the “docs” column in the API table, by default True
show_desc (bool, optional) – If True, include the “description” column in the API table, by default True
kwargs (Any) – Other kwargs for Table.pprint (pretty print) method

Returns:

Table – An Astropy Table of information

Raises:

TypeError – when the input value is not a string
ValueError – when the input value is not either “apis” or “domains”

generate_rst_table(value: str, show_docs: bool = True, show_desc: bool = True, **kwargs) → str[source]¶

Generate a rst-formatted table

Generates an rst-formatted table of the available domains or APIs using the tabulate python package. This method is good for dropping tables into Sphinx documentation.

Parameters:

value (str) – Either “api(s)” or “domain(s)”
show_docs (bool, optional) – If True, include the “docs” column in the API table, by default True
show_desc (bool, optional) – If True, include the “description” column in the API table, by default True
kwargs (Any) – Other kwargs for the tabulate method

Returns:

str – The rst formatted table as a string

Raises:

ImportError – when the tabulate package is not installed.

identify_api_from_url(url: str) → tuple[source]¶

Identify and extract an API and domain type from a URL.

Identifies the type of API and domain name the input URL is using. Loops over all available API and domain profiles in the ApiManager checks against extracted url parts from urlparse.

Parameters:: url (str) – The full url string
Returns:: tuple – The identified API profile and domain name
Raises:: ValueError – when the url does not start with http

list_apis() → list[source]¶

List the available SDSS APIs

Displays the complete list of available SDSS APIs.

Returns:: list – The list of available SDSS APIs

list_domains() → list[source]¶

List the available SDSS domains

Displays the complete list of available SDSS domain names.

Returns:: list – The list of available SDSS domains

set_profile(name: str, domain: str | None = None, test: bool | None = None) → None[source]¶

Set the current API profile

Sets the current API to the named profile

Parameters:

name (str) – The name of the API
domain (str, optional) – The name of the domain to switch to, by default None
test (bool, optional) – If True, sets the API profile to development, by default None

Bases: object

Class representing an API profile

This class provides an interface for a given SDSS API profile. It provides convenience methods for easily switching domain hosts for a given API, switching between production and development paths, and constructing full url route paths. It uses the urlparse URL scheme, “scheme://netloc/path;parameters?query#fragment”.

Parameters:

name (str) – The name of the API profile
domain (str, optional) – The name of the domain to use, by default None
port (int, optional) – The port used for localhost domains, by default None
ngrokid (int, optional) – The ngrok id used for localhost domains, by default None
test (bool, optional) – If True, use the development url, by default None

Variables:

description (str) – A description of the API
documentation (str) – A url link to any documentation of the API
auth_type (str) – The type of authentication needed for the API
domains (dict) – The available domains this API can be accessed on
mirrors (dict) – The available domains acting as mirrors
url (str) – The current constructed base API url
current_domain (str) – The current domain the API it set to use
name (str) – The name of the API profile
token (str) – The authenticated token, if any
info (dict) – A dictionary of information extracted from Pydantic datamodel

Raises:

ValueError – when input name does not match a valid API profile

change_domain(domain: str, port: int = None, ngrokid: int = None) → None[source]¶

Change the url domain

Updates the url “netloc” segment to use the domain name provided. If the domain is “local”, also needs either a port number or ngrok id to fully construct a local domain name.

Parameters:

domain (str) – The name of the domain to use
port (int, optional) – The port used for localhost domains, by default None
ngrokid (int, optional) – The ngrok id used for localhost domains, by default None

Example

>>> p = ApiProfile('marvin')
>>> p.url
'https://sas.sdss.org/marvin/api'
>>> p.change_domains('dr15')
>>> p.url
'https://dr15.sdss.org/marvin/api'

change_path(test: bool | None = None, public: bool | None = None) → None[source]¶

Change the url path

Updates the url “path” segment. Called without arguments, with update the path to the production base. If either “test” or “public” is set will update the path with the corresponding stems, used to switch to development urls.

Parameters:

test (bool, optional) – If True, add the “test” stem for the development path, by default None
public (bool, optional) – If True, adds the “public” stem for the deveopment path, by default None

Example

>>> p = ApiProfile('marvin')
>>> p.url
'https://sas.sdss.org/marvin/api'
>>> p.change_path(test=True)
>>> p.url
'https://sas.sdss.org/test/marvin/api'

check_for_refresh_token() → str[source]¶: Checks for a proper auth refresh token set as a envvar or in custom config

check_for_token() → str[source]¶: Checks for a proper auth token set as a envvar or in custom config

construct_route(route: str) → str[source]¶

Construct a full url to an input route

Constructs a full url path to the input route.

Parameters:: route (str) – The route component url path
Returns:: str – The full route url

Example

>>> p = ApiProfile('marvin')
>>> p.url
'https://sas.sdss.org/marvin/api'
>>> p.construct_route('general/getroutemap')
'https://sas.sdss.org/marvin/api/general/getroutemap'

construct_token_url(refresh: bool | None = None) → str[source]¶

Construct a login url for requesting tokens

Constructs an API url endpoint for logging in

Parameters:: refresh (bool, optional) – Set to construct a refresh route endpoint, by default None
Returns:: str – The URL of the API login endpoint
Raises:: ValueError – when no token route is found in the API profile

construct_url(test: bool | None = None, public: bool | None = None) → str[source]¶

Constructs a new base url

Constructs a new url given the currently set domain name and the API base name. Can optionally specify a development base using the test or public keywords.

Parameters:

test (bool, optional) – If True, add the “test” stem for the development path, by default None
public (bool, optional) – If True, adds the “public” stem for the deveopment path, by default None

Returns:

str – [description]

get_token(user: str) → dict[source]¶

Request and receive a valid API auth token

Requests an auth token for the specified user. This uses found netrc authentication to attempt to request and retrieve a valid token. The token should be saved in an “XXX_API_TOKEN” environment variable or in the custom sdss_brain.yml configuration file as “xxx_api_token”, where “XXX” is the API profile name.

Returns a dictionary containing an “access” key with your main auth token. Optionally contains a “refresh” key with a token for refreshing your access token. The refresh token should be saved in an “XXX_API_REFRESH_TOKEN” environment variable or in the custom sdss_brain.yml config file as “xxx_api_refresh_token”.

Parameters:

user (str) – The name of the SDSS user

Returns:

dict – A dict of valid API “access” and “refresh” auth token(s)

Raises:

BrainError – when the user is not netrc validated
BrainError – when a token cannot be extracted from the http response

refresh_auth_token() → str[source]¶

Refresh an auth access token

Uses the refresh_token to refresh your API authorization. Regenerates a new token to be used with the API.

Returns:: str – A new access token to replace your expired one

property is_domain_public: bool¶: Checks if current domain is a public one

property refresh_token: str¶: Returns an authentication refresh token

property token: str¶: Returns an authentication token

class sdss_brain.api.manager.ApiProfileModel(*, domains: List[str], base: str, mirrors: List[str] = None, stems: Dict[str, str] = {'affix': 'prefix', 'public': 'public', 'test': 'test'}, api: bool = False, routemap: str = None, auth: Dict[str, str] = {'route': None, 'type': 'netrc'}, description: str = '', docs: str = None)[source]¶

Bases: BaseModel

Pydantic class handling validation for SDSS API profiles

classmethod allowed_affixes(values)[source]¶

classmethod domains_in_list(values)[source]¶

api: bool¶

auth: Dict[str, str]¶

base: str¶

description: str¶

docs: str¶

domains: List[str]¶

mirrors: List[str]¶

model_config: ClassVar[ConfigDict] = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

routemap: str¶

stems: Dict[str, str]¶

class sdss_brain.api.manager.Domain(*, name: str, public: bool = False, description: str = None)[source]¶

Bases: BaseModel

Pydantic class handling validation for SDSS domains

classmethod check_domain_name(value)[source]¶

description: str¶

model_config: ClassVar[ConfigDict] = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str¶

public: bool¶

sdss_brain.api.io.send_post_request(url: str, data: dict | None = None, headers: dict | None = None) → dict[source]¶

A simple httpx post request

A simple standalone httpx post request to a specified url, and given an optional data payload.

Parameters:

url (str) – The url to send the request to
data (dict, optional) – Input data to send along with the request, by default None
headers (dict, optional) – Optional custom request header info, by default None

Returns:

dict – Extracted response data from response.json()

Raises:

BrainError – when an error occurs sending the request

Auth¶

class sdss_brain.auth.netrc.Netrc(path: str | None = None)[source]¶

Bases: object

Class representing a netrc file

This class represents a local .netrc file, used for authenticating users against remote machines. This class validates a netrc file for existence and correct permissions. It also checks its hosts against the allowed SDSS host domains data.sdss.org and api.sdss.org and ensures their presence.

Parameters:: path (str) – The path to a .netrc file. Defaults to custom “netrc_path” config path or ~/.netrc

check_host(host: str) → bool[source]¶

Checks the host against the local netrc file

Checks if the host is a valid machine in the netrc file

Parameters:: host (str) – The netrc machine name
Returns:: bool – True if the host is valid

check_netrc() → None[source]¶: Validates the netrc file

read_netrc(host: str) → tuple[source]¶

Read the netrc file for a given host

Reads the username, password for the given host machine. Note this returns plaintext username and password. Do not write out these values some place transparent and publicly visible.

Parameters:: host (str) – The netrc machine name
Returns:: tuple – Plain text netrc username, password
Raises:: BrainError – when netrc file fails to pass checks

property is_valid: bool¶: Checks for a valid netrc file

property valid_hosts: list¶: A list of valid netrc machine hosts

class sdss_brain.auth.htpass.Htpass(path: str | None = None)[source]¶

Bases: object

Class representing a htpasswd file

This class represents a local .htpasswd file, used for authenticating users against the Apache password file used for HTTP Basic Authentication. This class validates a htpasswd file for existence. It allows one to list the user entries found in a local htpasswd file, as well as validate a user against the htpasswd file.

Parameters:: path (str) – The path to a .htpasswd file. Defaults to custom “htpass_path” config path or ~/.htpasswd

list_users() → list[source]¶

Return a list of users in the htpasswd file

Returns:: list – list of users in the htpasswd file

validate_user(username: str, password: str) → bool[source]¶

Validate a user entry in the htpass file

Checks the provided username and password against the entry in the htpass file.

Parameters:

username (str) – A valid htpass username entry
password (str) – The password for the provided username

Returns:

bool – True when the username/password validates successfully

property is_valid: bool¶: Checks if the htpass file exists and htpass object is loaded

class sdss_brain.auth.user.User(user: str)[source]¶

Bases: object

Class representing a valid user

This class represents a valid SDSS user. It checks and validates the user against a local netrc file, a local htpasswd file, and against the SDSS collaboration.Credentials.

Parameters:

user (str) – the SDSS username

Variables:

member (dict) – dictionary of member information for a validated user
netrc (type[Netrc]) – A local Netrc instance, if any
htpass (type[Htpass]) – A local Htpass instance, if any
cred (type[Credential]) – A local SDSS Credential instance, if any

validate_user(password: str | None = None) → None[source]¶

Validate the given user

Validates the given user for netrc, htpass, and SDSS Credential authentication. Attempts to extract a valid password from the netrc file for the given user. Otherwise a password must be explicitly input.

Parameters:

password (str, optional) – The password for the given user, by default None

Raises: