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: Optional[str] = None, test: Optional[bool] = 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

class sdss_brain.api.manager.ApiProfile(name: str, domain: Optional[str] = None, port: Optional[int] = None, ngrokid: Optional[int] = None, release: Optional[str] = None, test: Optional[bool] = None)[source]

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: Optional[bool] = None, public: Optional[bool] = 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_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() str[source]

Construct a login url for requesting tokens

construct_url(test: Optional[bool] = None, public: Optional[bool] = 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) str[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.

Parameters

user (str) – The name of the SDSS user

Returns

str – A valid API auth token

Raises
  • BrainError – when the user is not netrc validated

  • BrainError – when a token cannot be extracted from the http response

property is_domain_public: bool

Checks if current domain is a public one

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]
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
name: str
public: bool
sdss_brain.api.io.send_post_request(url: str, data: Optional[dict] = 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

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: Optional[str] = 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
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: Optional[str] = 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: Optional[str] = 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
  • ValueError – when the netrc username does not match the input user

  • ValueError – when no valid password is input nor extracted from the netrc

property in_sdss: dict

Checks member status in SDSS-IV and SDSS-V

property is_htpass_valid: bool

Checks if htpasswd credentials are validated for the given user

property is_netrc_valid: bool

Checks if the netrc credentials are validated for the given user

property is_sdss_cred_valid: bool

Checks if SDSS credentials are validated for the given user

property validated: bool

Checks if user is validated

Config

Core

Mixins

Helpers

Tools

Exceptions

exception sdss_brain.exceptions.BrainAPIError(message=None)[source]

Bases: BrainError

A custom exception for API errors

exception sdss_brain.exceptions.BrainApiAuthError(message=None)[source]

Bases: BrainAPIError

A custom exception for API authentication errors

exception sdss_brain.exceptions.BrainDeprecationWarning[source]

Bases: BrainUserWarning

A warning for deprecated features.

exception sdss_brain.exceptions.BrainError(message=None)[source]

Bases: Exception

A custom core Brain exception

exception sdss_brain.exceptions.BrainMissingDependency(message=None)[source]

Bases: BrainError

A custom exception for missing dependencies.

exception sdss_brain.exceptions.BrainNotImplemented(message=None)[source]

Bases: BrainError

A custom exception for not yet implemented features.

exception sdss_brain.exceptions.BrainSkippedTestWarning[source]

Bases: BrainUserWarning

A warning for when a test is skipped.

exception sdss_brain.exceptions.BrainUserWarning[source]

Bases: UserWarning, BrainWarning

The primary warning class.

exception sdss_brain.exceptions.BrainWarning[source]

Bases: Warning

Base warning for Brain.