Module pyaurorax.search.sources

Manage AuroraX data sources utilized by the search engine.

Sub-modules

pyaurorax.search.sources.classes

Class definitions used by the sources submodule

Classes

class DataSource (identifier: int | None = None,
program: str | None = None,
platform: str | None = None,
instrument_type: str | None = None,
source_type: str | None = None,
display_name: str | None = None,
metadata: Dict | None = None,
owner: str | None = None,
maintainers: List[str] | None = None,
ephemeris_metadata_schema: List[Dict] | None = None,
data_product_metadata_schema: List[Dict] | None = None,
stats: DataSourceStatistics | None = None,
format: str = 'full_record')

Expand source code

class DataSource:
    """
    AuroraX data source record

    Attributes:
        identifier (int): the unique AuroraX data source identifier
        program (str): the program for this data source
        platform (str): the platform for this data source
        instrument_type (str): the instrument type for this data source
        source_type (str): the data source type for this data source. Options are
            in the pyaurorax.search.sources module, or at the top level using the
            pyaurorax.search.SOURCE_TYPE_* variables.
        display_name (str): the display name for this data source
        metadata (Dict): metadata for this data source (arbitrary keys and values)
        owner (str): the owner's email address of this data source
        maintainers (List[str]): the email addresses of AuroraX accounts that can alter
            this data source and its associated records
        ephemeris_metadata_schema (Dict): a list of dictionaries capturing the metadata
            keys and values that can appear in ephemeris records associated with
            this data source
        data_product_metadata_schema (Dict): a list of dictionaries capturing the metadata
            keys and values that can appear in data product records associated with
            this data source
        format (str): the format used when printing the data source, defaults to
            "full_record". Other options are in the pyaurorax.search.sources module, or
            at the top level using the pyaurorax.search.FORMAT_* variables.
    """

    def __init__(self,
                 identifier: Optional[int] = None,
                 program: Optional[str] = None,
                 platform: Optional[str] = None,
                 instrument_type: Optional[str] = None,
                 source_type: Optional[str] = None,
                 display_name: Optional[str] = None,
                 metadata: Optional[Dict] = None,
                 owner: Optional[str] = None,
                 maintainers: Optional[List[str]] = None,
                 ephemeris_metadata_schema: Optional[List[Dict]] = None,
                 data_product_metadata_schema: Optional[List[Dict]] = None,
                 stats: Optional[DataSourceStatistics] = None,
                 format: str = FORMAT_FULL_RECORD):
        self.identifier = identifier
        self.program = program
        self.platform = platform
        self.instrument_type = instrument_type
        self.source_type = source_type
        self.display_name = display_name
        self.metadata = metadata
        self.owner = owner
        self.maintainers = maintainers
        self.ephemeris_metadata_schema = ephemeris_metadata_schema
        self.data_product_metadata_schema = data_product_metadata_schema
        self.stats = stats
        self.format = format

    def __str__(self) -> str:
        return self.__repr__()

    def __repr__(self) -> str:
        return "DataSource(identifier=%s, program='%s', platform='%s', instrument_type='%s', source_type='%s', display_name='%s', ...)" % (
            self.identifier,
            self.program,
            self.platform,
            self.instrument_type,
            self.source_type,
            self.display_name,
        )

    def pretty_print(self):
        """
        A special print output for this class.
        """
        max_len = 80
        print("DataSource:")
        print("  %-30s: %d" % ("identifier", self.identifier))
        print("  %-30s: %s" % ("program", self.program))
        print("  %-30s: %s" % ("platform", self.platform))
        print("  %-30s: %s" % ("instrument_type", self.instrument_type))
        print("  %-30s: %s" % ("source_type", self.source_type))
        print("  %-30s: %s" % ("display_name", self.display_name))
        print("  %-30s: %s" % ("metadata", self.metadata))
        print("  %-30s: %s" % ("owner", self.owner))
        print("  %-30s: %s" % ("maintainers", self.maintainers))
        if (self.ephemeris_metadata_schema is not None and len(str(self.ephemeris_metadata_schema)) > max_len):
            ephemeris_metadata_schema_str = "%s..." % (str(self.ephemeris_metadata_schema)[0:max_len])
        else:
            ephemeris_metadata_schema_str = self.ephemeris_metadata_schema
        print("  %-30s: %s" % ("ephemeris_metadata_schema", ephemeris_metadata_schema_str))
        if (self.data_product_metadata_schema is not None and len(str(self.data_product_metadata_schema)) > max_len):
            data_product_metadata_schema_str = "%s..." % (str(self.data_product_metadata_schema)[0:max_len])
        else:
            data_product_metadata_schema_str = self.data_product_metadata_schema
        print("  %-30s: %s" % ("data_product_metadata_schema", data_product_metadata_schema_str))
        if (self.stats is not None and len(str(self.stats)) > max_len):
            stats_str = "%s..." % (str(self.stats)[0:max_len])
        else:
            stats_str = self.data_product_metadata_schema
        print("  %-30s: %s" % ("stats", stats_str))
        print("  %-30s: %s" % ("format", self.format))

AuroraX data source record

Attributes

identifier : int

the unique AuroraX data source identifier

program : str

the program for this data source

platform : str

the platform for this data source

instrument_type : str

the instrument type for this data source

source_type : str

the data source type for this data source. Options are in the pyaurorax.search.sources module, or at the top level using the pyaurorax.search.SOURCE_TYPE_* variables.

display_name : str

the display name for this data source

metadata : Dict

metadata for this data source (arbitrary keys and values)

owner : str

the owner's email address of this data source

maintainers : List[str]

the email addresses of AuroraX accounts that can alter this data source and its associated records

ephemeris_metadata_schema : Dict

a list of dictionaries capturing the metadata keys and values that can appear in ephemeris records associated with this data source

data_product_metadata_schema : Dict

a list of dictionaries capturing the metadata keys and values that can appear in data product records associated with this data source

format : str

the format used when printing the data source, defaults to "full_record". Other options are in the pyaurorax.search.sources module, or at the top level using the pyaurorax.search.FORMAT_* variables.

Methods

def pretty_print(self)

Expand source code

def pretty_print(self):
    """
    A special print output for this class.
    """
    max_len = 80
    print("DataSource:")
    print("  %-30s: %d" % ("identifier", self.identifier))
    print("  %-30s: %s" % ("program", self.program))
    print("  %-30s: %s" % ("platform", self.platform))
    print("  %-30s: %s" % ("instrument_type", self.instrument_type))
    print("  %-30s: %s" % ("source_type", self.source_type))
    print("  %-30s: %s" % ("display_name", self.display_name))
    print("  %-30s: %s" % ("metadata", self.metadata))
    print("  %-30s: %s" % ("owner", self.owner))
    print("  %-30s: %s" % ("maintainers", self.maintainers))
    if (self.ephemeris_metadata_schema is not None and len(str(self.ephemeris_metadata_schema)) > max_len):
        ephemeris_metadata_schema_str = "%s..." % (str(self.ephemeris_metadata_schema)[0:max_len])
    else:
        ephemeris_metadata_schema_str = self.ephemeris_metadata_schema
    print("  %-30s: %s" % ("ephemeris_metadata_schema", ephemeris_metadata_schema_str))
    if (self.data_product_metadata_schema is not None and len(str(self.data_product_metadata_schema)) > max_len):
        data_product_metadata_schema_str = "%s..." % (str(self.data_product_metadata_schema)[0:max_len])
    else:
        data_product_metadata_schema_str = self.data_product_metadata_schema
    print("  %-30s: %s" % ("data_product_metadata_schema", data_product_metadata_schema_str))
    if (self.stats is not None and len(str(self.stats)) > max_len):
        stats_str = "%s..." % (str(self.stats)[0:max_len])
    else:
        stats_str = self.data_product_metadata_schema
    print("  %-30s: %s" % ("stats", stats_str))
    print("  %-30s: %s" % ("format", self.format))

A special print output for this class.

class DataSourceStatistics (ephemeris_count: int,
data_product_count: int,
earliest_ephemeris_loaded: datetime.datetime | None = None,
latest_ephemeris_loaded: datetime.datetime | None = None,
earliest_data_product_loaded: datetime.datetime | None = None,
latest_data_product_loaded: datetime.datetime | None = None)

Expand source code

class DataSourceStatistics:
    """
    Data source statistics information

    Attributes:
        ephemeris_count (int): total number of ephemeris records for this data source
        data_product_count (int): total number of ephemeris records for this data source
        earliest_ephemeris_loaded (datetime.datetime): timestamp of the earliest ephemeris record
        latest_ephemeris_loaded (datetime.datetime): timestamp of the latest ephemeris record
        earliest_data_product_loaded (datetime.datetime): timestamp of the earliest data_product record
        latest_data_product_loaded (datetime.datetime): timestamp of the latest data product record
    """

    def __init__(self,
                 ephemeris_count: int,
                 data_product_count: int,
                 earliest_ephemeris_loaded: Optional[datetime.datetime] = None,
                 latest_ephemeris_loaded: Optional[datetime.datetime] = None,
                 earliest_data_product_loaded: Optional[datetime.datetime] = None,
                 latest_data_product_loaded: Optional[datetime.datetime] = None):
        self.ephemeris_count = ephemeris_count
        self.data_product_count = data_product_count
        self.earliest_ephemeris_loaded = earliest_ephemeris_loaded
        self.latest_ephemeris_loaded = latest_ephemeris_loaded
        self.earliest_data_product_loaded = earliest_data_product_loaded
        self.latest_data_product_loaded = latest_data_product_loaded

    def __str__(self) -> str:
        return self.__repr__()

    def __repr__(self) -> str:
        return "DataSourceStatistics(ephemeris_count=%d, data_product_count=%d, ...)" % (
            self.ephemeris_count,
            self.data_product_count,
        )

    def pretty_print(self):
        """
        A special print output for this class.
        """
        print("DataSourceStatistics:")
        print("  %-30s: %d" % ("ephemeris_count", self.ephemeris_count))
        print("  %-30s: %d" % ("data_product_count", self.data_product_count))
        print("  %-30s: %s" % ("earliest_ephemeris_loaded", self.earliest_ephemeris_loaded))
        print("  %-30s: %s" % ("latest_ephemeris_loaded", self.latest_ephemeris_loaded))
        print("  %-30s: %s" % ("earliest_data_product_loaded", self.earliest_data_product_loaded))
        print("  %-30s: %s" % ("latest_data_product_loaded", self.latest_data_product_loaded))

Data source statistics information

Attributes

ephemeris_count : int

total number of ephemeris records for this data source

data_product_count : int

total number of ephemeris records for this data source

earliest_ephemeris_loaded : datetime.datetime

timestamp of the earliest ephemeris record

latest_ephemeris_loaded : datetime.datetime

timestamp of the latest ephemeris record

earliest_data_product_loaded : datetime.datetime

timestamp of the earliest data_product record

latest_data_product_loaded : datetime.datetime

timestamp of the latest data product record

Methods

def pretty_print(self)

Expand source code

def pretty_print(self):
    """
    A special print output for this class.
    """
    print("DataSourceStatistics:")
    print("  %-30s: %d" % ("ephemeris_count", self.ephemeris_count))
    print("  %-30s: %d" % ("data_product_count", self.data_product_count))
    print("  %-30s: %s" % ("earliest_ephemeris_loaded", self.earliest_ephemeris_loaded))
    print("  %-30s: %s" % ("latest_ephemeris_loaded", self.latest_ephemeris_loaded))
    print("  %-30s: %s" % ("earliest_data_product_loaded", self.earliest_data_product_loaded))
    print("  %-30s: %s" % ("latest_data_product_loaded", self.latest_data_product_loaded))

A special print output for this class.

class SourcesManager (aurorax_obj)

Expand source code

class SourcesManager:
    """
    The SourcesManager object is initialized within every PyAuroraX object. It acts as a way to access 
    the submodules and carry over configuration information in the super class.
    """

    def __init__(self, aurorax_obj):
        self.__aurorax_obj = aurorax_obj

    def list(self,
             program: Optional[str] = None,
             platform: Optional[str] = None,
             instrument_type: Optional[str] = None,
             source_type: Optional[str] = None,
             owner: Optional[str] = None,
             format: Optional[str] = FORMAT_FULL_RECORD,
             order: Optional[str] = "identifier",
             include_stats: Optional[bool] = False) -> List[DataSource]:
        """
        Retrieve all data source records. Parameters can be used to filter as desired.

        Args:
            program (str): 
                the program to filter for, defaults to `None`
            platform (str): 
                the platform to filter for, defaults to `None`
            instrument_type (str): 
                the instrument type to filter for, defaults to `None`
            source_type (str): 
                the data source type to filter for, defaults to `None`. Options are in 
                the pyaurorax.search.sources module, or at the top level using the 
                pyaurorax.search.SOURCE_TYPE_* variables.
            owner (str): 
                the owner's email address to filter for, defaults to `None`
            format (str): 
                the format of the data sources returned, defaults to `classes.data_source.FORMAT_FULL_RECORD`. 
                Other options are in the pyaurorax.search.sources module, or at the top level using 
                the pyaurorax.search.FORMAT_* variables.
            order (str): 
                the category to order results by. Valid values are identifier, program, platform,
                instrument_type, display_name, or owner. Defaults to `identifier`
            include_stats (bool): 
                include additional stats information about the data source, defaults to `False`

        Returns:
            a list of `DataSource` records matching the requested parameters

        Raises:
            pyaurorax.exceptions.AuroraXAPIError: error during API call
        """
        return func_list(
            self.__aurorax_obj,
            program,
            platform,
            instrument_type,
            source_type,
            owner,
            format,
            order,
            include_stats,
        )

    def list_in_table(self,
                      program: Optional[str] = None,
                      platform: Optional[str] = None,
                      instrument_type: Optional[str] = None,
                      source_type: Optional[str] = None,
                      owner: Optional[str] = None,
                      order: Optional[str] = "identifier",
                      table_max_width: int = 200) -> None:
        """
        Display all data source records in a table. Parameters can be used to filter as desired.

        Args:
            program (str): 
                the program to filter for, defaults to `None`

            platform (str): 
                the platform to filter for, defaults to `None`

            instrument_type (str): 
                the instrument type to filter for, defaults to `None`

            source_type (str): 
                the data source type to filter for, defaults to `None`. Options are in 
                the pyaurorax.search.sources module, or at the top level using the 
                pyaurorax.search.SOURCE_TYPE_* variables.

            owner (str): 
                the owner's email address to filter for, defaults to `None`

            format (str): 
                the format of the data sources returned, defaults to `classes.data_source.FORMAT_FULL_RECORD`. 
                Other options are in the pyaurorax.search.sources module, or at the top level using 
                the pyaurorax.search.FORMAT_* variables.

            order (str): 
                the category to order results by. Valid values are identifier, program, platform,
                instrument_type, display_name, or owner. Defaults to `identifier`
                
            table_max_width (int): 
                table maximum width, defaults to 200

        Returns:
            No return, only prints a table

        Raises:
            pyaurorax.exceptions.AuroraXAPIError: error during API call
        """
        # get datasets
        datasets = func_list(
            self.__aurorax_obj,
            program,
            platform,
            instrument_type,
            source_type,
            owner,
            FORMAT_BASIC_INFO,
            order,
            False,
        )

        # set table lists
        table_identifiers = []
        table_programs = []
        table_platforms = []
        table_instrument_types = []
        table_source_types = []
        table_display_names = []
        for d in datasets:
            table_identifiers.append(d.identifier)
            table_programs.append(d.program)
            table_platforms.append(d.platform)
            table_instrument_types.append(d.instrument_type)
            table_source_types.append(d.source_type)
            table_display_names.append(d.display_name)

        # set header values
        table_headers = [
            "Identifier",
            "Program",
            "Platform",
            "Instrument Type",
            "Source Type",
            "Display Name",
        ]

        # print as table
        table = Texttable(max_width=table_max_width)
        table.set_deco(Texttable.HEADER)
        table.set_cols_dtype(["t"] * len(table_headers))
        table.set_header_align(["l"] * len(table_headers))
        table.set_cols_align(["l"] * len(table_headers))
        table.header(table_headers)
        for i in range(0, len(table_identifiers)):
            table.add_row([
                table_identifiers[i],
                table_programs[i],
                table_platforms[i],
                table_instrument_types[i],
                table_source_types[i],
                table_display_names[i],
            ])
        print(table.draw())

    def search(self,
               programs: Optional[List[str]] = [],
               platforms: Optional[List[str]] = [],
               instrument_types: Optional[List[str]] = [],
               format: Optional[str] = FORMAT_FULL_RECORD,
               order: Optional[str] = "identifier",
               include_stats: Optional[bool] = False) -> List[DataSource]:
        """
        Search for data source records. Parameters can be used to filter as desired.

        This function is very similar to the `list()` function, however multiple programs,
        platforms, and/or instrument types can be supplied here. The `list()` function only 
        supports single values for the parameters.

        Args:
            programs (List[str]): 
                the programs to search for, defaults to `[]`
            platforms (List[str]): 
                the platforms to search for, defaults to `[]`
            instrument_type (List[str]): 
                the instrument types to search for, defaults to `[]`
            format (str): 
                the format of the data sources returned, defaults to `classes.data_source.FORMAT_FULL_RECORD`. 
                Other options are in the pyaurorax.search.sources module, or at the top level using 
                the pyaurorax.search.FORMAT_* variables.
            order (str): 
                the category to order results by. Valid values are identifier, program, platform,
                instrument_type, display_name, or owner. Defaults to `identifier`
            include_stats (bool): 
                include additional stats information about the data source, defaults to `False`

        Returns:
            a list of `DataSource` records matching the requested parameters

        Raises:
            pyaurorax.exceptions.AuroraXAPIError: error during API call
        """
        return func_search(
            self.__aurorax_obj,
            programs,
            platforms,
            instrument_types,
            format,
            order,
            include_stats,
        )

    def get(self,
            program: str,
            platform: str,
            instrument_type: str,
            format: Optional[str] = FORMAT_FULL_RECORD,
            include_stats: Optional[bool] = False) -> DataSource:
        """
        Retrieve a specific data source record

        Args:
            program (str): 
                the program name
            platform (str): 
                the platform name
            instrument_type (str): 
                the instrument type name
            format (str): 
                the format of the data sources returned, defaults to `classes.data_source.FORMAT_FULL_RECORD`. 
                Other options are in the pyaurorax.search.sources module, or at the top level using 
                the pyaurorax.search.FORMAT_* variables.
            include_stats (bool): 
                include additional stats information about the data source, defaults to `False`

        Returns:
            the `DataSource` matching the requested parameters

        Raises:
            pyaurorax.exceptions.AuroraXAPIError: error during API call
            pyaurorax.exceptions.AuroraXNotFoundError: source not found
        """
        return func_get(
            self.__aurorax_obj,
            program,
            platform,
            instrument_type,
            format,
            include_stats,
        )

    def get_using_filters(self,
                          program: Optional[str] = None,
                          platform: Optional[str] = None,
                          instrument_type: Optional[str] = None,
                          source_type: Optional[str] = None,
                          owner: Optional[str] = None,
                          format: Optional[str] = FORMAT_FULL_RECORD,
                          order: Optional[str] = "identifier",
                          include_stats: Optional[bool] = False) -> List[DataSource]:
        """
        Retrieve all data sources matching a filter

        Args:
            program (str): 
                the program to filter for, defaults to `None`
            platform (str): 
                the platform to filter for, defaults to `None`
            instrument_type (str): 
                the instrument type to filter for, defaults to `None`
            source_type (str): 
                the data source type to filter for, defaults to `None`. Options are in 
                the pyaurorax.search.sources module, or at the top level using the 
                pyaurorax.search.SOURCE_TYPE_* variables.
            owner (str): 
                the owner's email address to filter for, defaults to `None`
            format (str): 
                the format of the data sources returned, defaults to `classes.data_source.FORMAT_FULL_RECORD`. 
                Other options are in the pyaurorax.search.sources module, or at the top level using 
                the pyaurorax.search.FORMAT_* variables.
            order (str): 
                the category to order results by. Valid values are identifier, program, platform,
                instrument_type, display_name, or owner. Defaults to `identifier`
            include_stats (bool): 
                include additional stats information about the data source, defaults to `False`.

        Returns:
            a list of `DataSource` records matching the requested parameters

        Raises:
            pyaurorax.exceptions.AuroraXAPIError: error during API call
        """
        return func_get_using_filters(
            self.__aurorax_obj,
            program,
            platform,
            instrument_type,
            source_type,
            owner,
            format,
            order,
            include_stats,
        )

    def get_using_identifier(self, identifier: int, format: Optional[str] = FORMAT_FULL_RECORD, include_stats: Optional[bool] = False) -> DataSource:
        """
        Retrieve data source for a specific identifier

        Args:
            identifier (int): 
                the AuroraX unique data source identifier number
            format (str): 
                the format of the data sources returned, defaults to `classes.data_source.FORMAT_FULL_RECORD`. 
                Other options are in the pyaurorax.search.sources module, or at the top level using 
                the pyaurorax.search.FORMAT_* variables.
            include_stats (bool): 
                include additional stats information about the data source, defaults to `False`

        Returns:
            the `DataSource` for the specified identifier

        Raises:
            pyaurorax.exceptions.AuroraXAPIError: error during API call
        """
        return func_get_using_identifier(self.__aurorax_obj, identifier, format, include_stats)

    def add(self, data_source: DataSource) -> DataSource:
        """
        Add a new data source to the AuroraX search engine

        Args:
            data_source (DataSource): 
                the data source to add (note: it must be a fully-defined DataSource object)

        Returns:
            the newly created `DataSource`.

        Raises:
            pyaurorax.exceptions.AuroraXAPIError: error during API call
            pyaurorax.exceptions.AuroraXUnauthorizedError: not allowed to perform task, or API key / user permissions are invalid
            pyaurorax.exceptions.AuroraXDuplicateError: duplicate data source, already exists
        """
        return func_add(self.__aurorax_obj, data_source)

    def delete(self, identifier: int) -> int:
        """
        Delete a data source from the AuroraX search engine

        Args:
            identifier (int): the data source unique identifier to delete

        Returns:
            0 on success, raises error if an issue was encountered

        Raises:
            pyaurorax.exceptions.AuroraXAPIError: error during API call
            pyaurorax.exceptions.AuroraXUnauthorizedError: not allowed to perform task, or API key / user permissions are invalid
            pyaurorax.exceptions.AuroraXNotFoundError: data source not found
            pyaurorax.exceptions.AuroraXConflictError: a conflict occurred
        """
        return func_delete(self.__aurorax_obj, identifier)

    def update(self,
               identifier: int,
               program: Optional[str] = None,
               platform: Optional[str] = None,
               instrument_type: Optional[str] = None,
               source_type: Optional[str] = None,
               display_name: Optional[str] = None,
               metadata: Optional[Dict] = None,
               owner: Optional[str] = None,
               maintainers: Optional[List[str]] = None,
               ephemeris_metadata_schema: Optional[List[Dict]] = None,
               data_product_metadata_schema: Optional[List[Dict]] = None) -> DataSource:
        """
        Update a data source in the AuroraX search engine. Omitted fields are ignored during the 
        update. 
        
        Note that the identifier cannot be updated. If you need to update the data source's identifier,
        we recommend deletion of the original data source and recreation using the desired identifier.

        Args:
            identifier (int): 
                the AuroraX unique identifier for the data source, required and cannot be updated
            program (str): 
                the new program for the data source, defaults to `None`
            platform (str): 
                the new platform for the data source, defaults to `None`
            instrument_type (str): 
                the new instrument type for the data source, defaults to `None`
            source_type (str): 
                the new source type for the data source, defaults to `None`. Options
                are in the pyaurorax.search.sources module, or at the top level using the
                pyaurorax.search.SOURCE_TYPE_* variables.
            display_name (str): 
                the new display name for the data source, defaults to `None`
            metadata (Dict): 
                the new metadata for the data source, defaults to `None`
            maintainers (str): 
                the new maintainer AuroraX account email addresses, defaults to `None`
            ephemeris_metadata_schema (List[Dict]): 
                a list of dictionaries capturing the metadata keys and values that can 
                appear in ephemeris records associated with the data source, defaults to `None`
            data_product_metadata_schema (List[Dict]): 
                a list of dictionaries capturing the metadata keys and values that can appear 
                in data product records associated with the data source, defaults to `None`

        Returns:
            the updated `DataSource` record

        Raises:
            pyaurorax.exceptions.AuroraXAPIError: error during API call
            pyaurorax.exceptions.AuroraXUnauthorizedError: not allowed to perform task, or API key / user permissions are invalid
            pyaurorax.exceptions.AuroraXNotFoundError: data source not found
        """
        return func_update(
            self.__aurorax_obj,
            identifier,
            program,
            platform,
            instrument_type,
            source_type,
            display_name,
            metadata,
            owner,
            maintainers,
            ephemeris_metadata_schema,
            data_product_metadata_schema,
        )

The SourcesManager object is initialized within every PyAuroraX object. It acts as a way to access the submodules and carry over configuration information in the super class.

Methods

def add(self,
data_source: DataSource) ‑> DataSource

Expand source code

def add(self, data_source: DataSource) -> DataSource:
    """
    Add a new data source to the AuroraX search engine

    Args:
        data_source (DataSource): 
            the data source to add (note: it must be a fully-defined DataSource object)

    Returns:
        the newly created `DataSource`.

    Raises:
        pyaurorax.exceptions.AuroraXAPIError: error during API call
        pyaurorax.exceptions.AuroraXUnauthorizedError: not allowed to perform task, or API key / user permissions are invalid
        pyaurorax.exceptions.AuroraXDuplicateError: duplicate data source, already exists
    """
    return func_add(self.__aurorax_obj, data_source)

Add a new data source to the AuroraX search engine

Args

data_source : DataSource

the data source to add (note: it must be a fully-defined DataSource object)

Returns

the newly created DataSource.

Raises

AuroraXAPIError

error during API call

AuroraXUnauthorizedError

not allowed to perform task, or API key / user permissions are invalid

AuroraXDuplicateError

duplicate data source, already exists

def delete(self, identifier: int) ‑> int

Expand source code

def delete(self, identifier: int) -> int:
    """
    Delete a data source from the AuroraX search engine

    Args:
        identifier (int): the data source unique identifier to delete

    Returns:
        0 on success, raises error if an issue was encountered

    Raises:
        pyaurorax.exceptions.AuroraXAPIError: error during API call
        pyaurorax.exceptions.AuroraXUnauthorizedError: not allowed to perform task, or API key / user permissions are invalid
        pyaurorax.exceptions.AuroraXNotFoundError: data source not found
        pyaurorax.exceptions.AuroraXConflictError: a conflict occurred
    """
    return func_delete(self.__aurorax_obj, identifier)

Delete a data source from the AuroraX search engine

Args

identifier : int

the data source unique identifier to delete

Returns

0 on success, raises error if an issue was encountered

Raises

AuroraXAPIError

error during API call

AuroraXUnauthorizedError

not allowed to perform task, or API key / user permissions are invalid

AuroraXNotFoundError

data source not found

AuroraXConflictError

a conflict occurred

def get(self,
program: str,
platform: str,
instrument_type: str,
format: str | None = 'full_record',
include_stats: bool | None = False) ‑> DataSource

Expand source code

def get(self,
        program: str,
        platform: str,
        instrument_type: str,
        format: Optional[str] = FORMAT_FULL_RECORD,
        include_stats: Optional[bool] = False) -> DataSource:
    """
    Retrieve a specific data source record

    Args:
        program (str): 
            the program name
        platform (str): 
            the platform name
        instrument_type (str): 
            the instrument type name
        format (str): 
            the format of the data sources returned, defaults to `classes.data_source.FORMAT_FULL_RECORD`. 
            Other options are in the pyaurorax.search.sources module, or at the top level using 
            the pyaurorax.search.FORMAT_* variables.
        include_stats (bool): 
            include additional stats information about the data source, defaults to `False`

    Returns:
        the `DataSource` matching the requested parameters

    Raises:
        pyaurorax.exceptions.AuroraXAPIError: error during API call
        pyaurorax.exceptions.AuroraXNotFoundError: source not found
    """
    return func_get(
        self.__aurorax_obj,
        program,
        platform,
        instrument_type,
        format,
        include_stats,
    )

Retrieve a specific data source record

Args

program : str

the program name

platform : str

the platform name

instrument_type : str

the instrument type name

format : str

the format of the data sources returned, defaults to FORMAT_FULL_RECORD. Other options are in the pyaurorax.search.sources module, or at the top level using the pyaurorax.search.FORMAT_* variables.

include_stats : bool

include additional stats information about the data source, defaults to False

Returns

the DataSource matching the requested parameters

Raises

AuroraXAPIError

error during API call

AuroraXNotFoundError

source not found

def get_using_filters(self,
program: str | None = None,
platform: str | None = None,
instrument_type: str | None = None,
source_type: str | None = None,
owner: str | None = None,
format: str | None = 'full_record',
order: str | None = 'identifier',
include_stats: bool | None = False) ‑> List[DataSource]

Expand source code

def get_using_filters(self,
                      program: Optional[str] = None,
                      platform: Optional[str] = None,
                      instrument_type: Optional[str] = None,
                      source_type: Optional[str] = None,
                      owner: Optional[str] = None,
                      format: Optional[str] = FORMAT_FULL_RECORD,
                      order: Optional[str] = "identifier",
                      include_stats: Optional[bool] = False) -> List[DataSource]:
    """
    Retrieve all data sources matching a filter

    Args:
        program (str): 
            the program to filter for, defaults to `None`
        platform (str): 
            the platform to filter for, defaults to `None`
        instrument_type (str): 
            the instrument type to filter for, defaults to `None`
        source_type (str): 
            the data source type to filter for, defaults to `None`. Options are in 
            the pyaurorax.search.sources module, or at the top level using the 
            pyaurorax.search.SOURCE_TYPE_* variables.
        owner (str): 
            the owner's email address to filter for, defaults to `None`
        format (str): 
            the format of the data sources returned, defaults to `classes.data_source.FORMAT_FULL_RECORD`. 
            Other options are in the pyaurorax.search.sources module, or at the top level using 
            the pyaurorax.search.FORMAT_* variables.
        order (str): 
            the category to order results by. Valid values are identifier, program, platform,
            instrument_type, display_name, or owner. Defaults to `identifier`
        include_stats (bool): 
            include additional stats information about the data source, defaults to `False`.

    Returns:
        a list of `DataSource` records matching the requested parameters

    Raises:
        pyaurorax.exceptions.AuroraXAPIError: error during API call
    """
    return func_get_using_filters(
        self.__aurorax_obj,
        program,
        platform,
        instrument_type,
        source_type,
        owner,
        format,
        order,
        include_stats,
    )

Retrieve all data sources matching a filter

Args

program : str

the program to filter for, defaults to None

platform : str

the platform to filter for, defaults to None

instrument_type : str

the instrument type to filter for, defaults to None

source_type : str

the data source type to filter for, defaults to None. Options are in the pyaurorax.search.sources module, or at the top level using the pyaurorax.search.SOURCE_TYPE_* variables.

owner : str

the owner's email address to filter for, defaults to None

format : str

the format of the data sources returned, defaults to FORMAT_FULL_RECORD. Other options are in the pyaurorax.search.sources module, or at the top level using the pyaurorax.search.FORMAT_* variables.

order : str

the category to order results by. Valid values are identifier, program, platform, instrument_type, display_name, or owner. Defaults to identifier

include_stats : bool

include additional stats information about the data source, defaults to False.

Returns

a list of DataSource records matching the requested parameters

Raises

AuroraXAPIError

error during API call

def get_using_identifier(self,
identifier: int,
format: str | None = 'full_record',
include_stats: bool | None = False) ‑> DataSource

Expand source code

def get_using_identifier(self, identifier: int, format: Optional[str] = FORMAT_FULL_RECORD, include_stats: Optional[bool] = False) -> DataSource:
    """
    Retrieve data source for a specific identifier

    Args:
        identifier (int): 
            the AuroraX unique data source identifier number
        format (str): 
            the format of the data sources returned, defaults to `classes.data_source.FORMAT_FULL_RECORD`. 
            Other options are in the pyaurorax.search.sources module, or at the top level using 
            the pyaurorax.search.FORMAT_* variables.
        include_stats (bool): 
            include additional stats information about the data source, defaults to `False`

    Returns:
        the `DataSource` for the specified identifier

    Raises:
        pyaurorax.exceptions.AuroraXAPIError: error during API call
    """
    return func_get_using_identifier(self.__aurorax_obj, identifier, format, include_stats)

Retrieve data source for a specific identifier

Args

identifier : int

the AuroraX unique data source identifier number

format : str

the format of the data sources returned, defaults to FORMAT_FULL_RECORD. Other options are in the pyaurorax.search.sources module, or at the top level using the pyaurorax.search.FORMAT_* variables.

include_stats : bool

include additional stats information about the data source, defaults to False

Returns

the DataSource for the specified identifier

Raises

AuroraXAPIError

error during API call

def list(self,
program: str | None = None,
platform: str | None = None,
instrument_type: str | None = None,
source_type: str | None = None,
owner: str | None = None,
format: str | None = 'full_record',
order: str | None = 'identifier',
include_stats: bool | None = False) ‑> List[DataSource]

Expand source code

def list(self,
         program: Optional[str] = None,
         platform: Optional[str] = None,
         instrument_type: Optional[str] = None,
         source_type: Optional[str] = None,
         owner: Optional[str] = None,
         format: Optional[str] = FORMAT_FULL_RECORD,
         order: Optional[str] = "identifier",
         include_stats: Optional[bool] = False) -> List[DataSource]:
    """
    Retrieve all data source records. Parameters can be used to filter as desired.

    Args:
        program (str): 
            the program to filter for, defaults to `None`
        platform (str): 
            the platform to filter for, defaults to `None`
        instrument_type (str): 
            the instrument type to filter for, defaults to `None`
        source_type (str): 
            the data source type to filter for, defaults to `None`. Options are in 
            the pyaurorax.search.sources module, or at the top level using the 
            pyaurorax.search.SOURCE_TYPE_* variables.
        owner (str): 
            the owner's email address to filter for, defaults to `None`
        format (str): 
            the format of the data sources returned, defaults to `classes.data_source.FORMAT_FULL_RECORD`. 
            Other options are in the pyaurorax.search.sources module, or at the top level using 
            the pyaurorax.search.FORMAT_* variables.
        order (str): 
            the category to order results by. Valid values are identifier, program, platform,
            instrument_type, display_name, or owner. Defaults to `identifier`
        include_stats (bool): 
            include additional stats information about the data source, defaults to `False`

    Returns:
        a list of `DataSource` records matching the requested parameters

    Raises:
        pyaurorax.exceptions.AuroraXAPIError: error during API call
    """
    return func_list(
        self.__aurorax_obj,
        program,
        platform,
        instrument_type,
        source_type,
        owner,
        format,
        order,
        include_stats,
    )

Retrieve all data source records. Parameters can be used to filter as desired.

Args

program : str

the program to filter for, defaults to None

platform : str

the platform to filter for, defaults to None

instrument_type : str

the instrument type to filter for, defaults to None

source_type : str

the data source type to filter for, defaults to None. Options are in the pyaurorax.search.sources module, or at the top level using the pyaurorax.search.SOURCE_TYPE_* variables.

owner : str

the owner's email address to filter for, defaults to None

format : str

the format of the data sources returned, defaults to FORMAT_FULL_RECORD. Other options are in the pyaurorax.search.sources module, or at the top level using the pyaurorax.search.FORMAT_* variables.

order : str

the category to order results by. Valid values are identifier, program, platform, instrument_type, display_name, or owner. Defaults to identifier

include_stats : bool

include additional stats information about the data source, defaults to False

Returns

a list of DataSource records matching the requested parameters

Raises

AuroraXAPIError

error during API call

def list_in_table(self,
program: str | None = None,
platform: str | None = None,
instrument_type: str | None = None,
source_type: str | None = None,
owner: str | None = None,
order: str | None = 'identifier',
table_max_width: int = 200) ‑> None

Expand source code

def list_in_table(self,
                  program: Optional[str] = None,
                  platform: Optional[str] = None,
                  instrument_type: Optional[str] = None,
                  source_type: Optional[str] = None,
                  owner: Optional[str] = None,
                  order: Optional[str] = "identifier",
                  table_max_width: int = 200) -> None:
    """
    Display all data source records in a table. Parameters can be used to filter as desired.

    Args:
        program (str): 
            the program to filter for, defaults to `None`

        platform (str): 
            the platform to filter for, defaults to `None`

        instrument_type (str): 
            the instrument type to filter for, defaults to `None`

        source_type (str): 
            the data source type to filter for, defaults to `None`. Options are in 
            the pyaurorax.search.sources module, or at the top level using the 
            pyaurorax.search.SOURCE_TYPE_* variables.

        owner (str): 
            the owner's email address to filter for, defaults to `None`

        format (str): 
            the format of the data sources returned, defaults to `classes.data_source.FORMAT_FULL_RECORD`. 
            Other options are in the pyaurorax.search.sources module, or at the top level using 
            the pyaurorax.search.FORMAT_* variables.

        order (str): 
            the category to order results by. Valid values are identifier, program, platform,
            instrument_type, display_name, or owner. Defaults to `identifier`
            
        table_max_width (int): 
            table maximum width, defaults to 200

    Returns:
        No return, only prints a table

    Raises:
        pyaurorax.exceptions.AuroraXAPIError: error during API call
    """
    # get datasets
    datasets = func_list(
        self.__aurorax_obj,
        program,
        platform,
        instrument_type,
        source_type,
        owner,
        FORMAT_BASIC_INFO,
        order,
        False,
    )

    # set table lists
    table_identifiers = []
    table_programs = []
    table_platforms = []
    table_instrument_types = []
    table_source_types = []
    table_display_names = []
    for d in datasets:
        table_identifiers.append(d.identifier)
        table_programs.append(d.program)
        table_platforms.append(d.platform)
        table_instrument_types.append(d.instrument_type)
        table_source_types.append(d.source_type)
        table_display_names.append(d.display_name)

    # set header values
    table_headers = [
        "Identifier",
        "Program",
        "Platform",
        "Instrument Type",
        "Source Type",
        "Display Name",
    ]

    # print as table
    table = Texttable(max_width=table_max_width)
    table.set_deco(Texttable.HEADER)
    table.set_cols_dtype(["t"] * len(table_headers))
    table.set_header_align(["l"] * len(table_headers))
    table.set_cols_align(["l"] * len(table_headers))
    table.header(table_headers)
    for i in range(0, len(table_identifiers)):
        table.add_row([
            table_identifiers[i],
            table_programs[i],
            table_platforms[i],
            table_instrument_types[i],
            table_source_types[i],
            table_display_names[i],
        ])
    print(table.draw())

Display all data source records in a table. Parameters can be used to filter as desired.

Args

program : str

the program to filter for, defaults to None

platform : str

the platform to filter for, defaults to None

instrument_type : str

the instrument type to filter for, defaults to None

source_type : str

the data source type to filter for, defaults to None. Options are in the pyaurorax.search.sources module, or at the top level using the pyaurorax.search.SOURCE_TYPE_* variables.

owner : str

the owner's email address to filter for, defaults to None

format : str

the format of the data sources returned, defaults to FORMAT_FULL_RECORD. Other options are in the pyaurorax.search.sources module, or at the top level using the pyaurorax.search.FORMAT_* variables.

order : str

the category to order results by. Valid values are identifier, program, platform, instrument_type, display_name, or owner. Defaults to identifier

table_max_width : int

table maximum width, defaults to 200

Returns

No return, only prints a table

Raises

AuroraXAPIError

error during API call

def search(self,
programs: List[str] | None = [],
platforms: List[str] | None = [],
instrument_types: List[str] | None = [],
format: str | None = 'full_record',
order: str | None = 'identifier',
include_stats: bool | None = False) ‑> List[DataSource]

Expand source code

def search(self,
           programs: Optional[List[str]] = [],
           platforms: Optional[List[str]] = [],
           instrument_types: Optional[List[str]] = [],
           format: Optional[str] = FORMAT_FULL_RECORD,
           order: Optional[str] = "identifier",
           include_stats: Optional[bool] = False) -> List[DataSource]:
    """
    Search for data source records. Parameters can be used to filter as desired.

    This function is very similar to the `list()` function, however multiple programs,
    platforms, and/or instrument types can be supplied here. The `list()` function only 
    supports single values for the parameters.

    Args:
        programs (List[str]): 
            the programs to search for, defaults to `[]`
        platforms (List[str]): 
            the platforms to search for, defaults to `[]`
        instrument_type (List[str]): 
            the instrument types to search for, defaults to `[]`
        format (str): 
            the format of the data sources returned, defaults to `classes.data_source.FORMAT_FULL_RECORD`. 
            Other options are in the pyaurorax.search.sources module, or at the top level using 
            the pyaurorax.search.FORMAT_* variables.
        order (str): 
            the category to order results by. Valid values are identifier, program, platform,
            instrument_type, display_name, or owner. Defaults to `identifier`
        include_stats (bool): 
            include additional stats information about the data source, defaults to `False`

    Returns:
        a list of `DataSource` records matching the requested parameters

    Raises:
        pyaurorax.exceptions.AuroraXAPIError: error during API call
    """
    return func_search(
        self.__aurorax_obj,
        programs,
        platforms,
        instrument_types,
        format,
        order,
        include_stats,
    )

Search for data source records. Parameters can be used to filter as desired.

This function is very similar to the list() function, however multiple programs, platforms, and/or instrument types can be supplied here. The list() function only supports single values for the parameters.

Args

programs : List[str]

the programs to search for, defaults to []

platforms : List[str]

the platforms to search for, defaults to []

instrument_type : List[str]

the instrument types to search for, defaults to []

format : str

the format of the data sources returned, defaults to FORMAT_FULL_RECORD. Other options are in the pyaurorax.search.sources module, or at the top level using the pyaurorax.search.FORMAT_* variables.

order : str

the category to order results by. Valid values are identifier, program, platform, instrument_type, display_name, or owner. Defaults to identifier

include_stats : bool

include additional stats information about the data source, defaults to False

Returns

a list of DataSource records matching the requested parameters

Raises

AuroraXAPIError

error during API call

def update(self,
identifier: int,
program: str | None = None,
platform: str | None = None,
instrument_type: str | None = None,
source_type: str | None = None,
display_name: str | None = None,
metadata: Dict | None = None,
owner: str | None = None,
maintainers: List[str] | None = None,
ephemeris_metadata_schema: List[Dict] | None = None,
data_product_metadata_schema: List[Dict] | None = None) ‑> DataSource

Expand source code

def update(self,
           identifier: int,
           program: Optional[str] = None,
           platform: Optional[str] = None,
           instrument_type: Optional[str] = None,
           source_type: Optional[str] = None,
           display_name: Optional[str] = None,
           metadata: Optional[Dict] = None,
           owner: Optional[str] = None,
           maintainers: Optional[List[str]] = None,
           ephemeris_metadata_schema: Optional[List[Dict]] = None,
           data_product_metadata_schema: Optional[List[Dict]] = None) -> DataSource:
    """
    Update a data source in the AuroraX search engine. Omitted fields are ignored during the 
    update. 
    
    Note that the identifier cannot be updated. If you need to update the data source's identifier,
    we recommend deletion of the original data source and recreation using the desired identifier.

    Args:
        identifier (int): 
            the AuroraX unique identifier for the data source, required and cannot be updated
        program (str): 
            the new program for the data source, defaults to `None`
        platform (str): 
            the new platform for the data source, defaults to `None`
        instrument_type (str): 
            the new instrument type for the data source, defaults to `None`
        source_type (str): 
            the new source type for the data source, defaults to `None`. Options
            are in the pyaurorax.search.sources module, or at the top level using the
            pyaurorax.search.SOURCE_TYPE_* variables.
        display_name (str): 
            the new display name for the data source, defaults to `None`
        metadata (Dict): 
            the new metadata for the data source, defaults to `None`
        maintainers (str): 
            the new maintainer AuroraX account email addresses, defaults to `None`
        ephemeris_metadata_schema (List[Dict]): 
            a list of dictionaries capturing the metadata keys and values that can 
            appear in ephemeris records associated with the data source, defaults to `None`
        data_product_metadata_schema (List[Dict]): 
            a list of dictionaries capturing the metadata keys and values that can appear 
            in data product records associated with the data source, defaults to `None`

    Returns:
        the updated `DataSource` record

    Raises:
        pyaurorax.exceptions.AuroraXAPIError: error during API call
        pyaurorax.exceptions.AuroraXUnauthorizedError: not allowed to perform task, or API key / user permissions are invalid
        pyaurorax.exceptions.AuroraXNotFoundError: data source not found
    """
    return func_update(
        self.__aurorax_obj,
        identifier,
        program,
        platform,
        instrument_type,
        source_type,
        display_name,
        metadata,
        owner,
        maintainers,
        ephemeris_metadata_schema,
        data_product_metadata_schema,
    )

Update a data source in the AuroraX search engine. Omitted fields are ignored during the update.

Note that the identifier cannot be updated. If you need to update the data source's identifier, we recommend deletion of the original data source and recreation using the desired identifier.

Args

identifier : int

the AuroraX unique identifier for the data source, required and cannot be updated

program : str

the new program for the data source, defaults to None

platform : str

the new platform for the data source, defaults to None

instrument_type : str

the new instrument type for the data source, defaults to None

source_type : str

the new source type for the data source, defaults to None. Options are in the pyaurorax.search.sources module, or at the top level using the pyaurorax.search.SOURCE_TYPE_* variables.

display_name : str

the new display name for the data source, defaults to None

metadata : Dict

the new metadata for the data source, defaults to None

maintainers : str

the new maintainer AuroraX account email addresses, defaults to None

ephemeris_metadata_schema : List[Dict]

a list of dictionaries capturing the metadata keys and values that can appear in ephemeris records associated with the data source, defaults to None

data_product_metadata_schema : List[Dict]

a list of dictionaries capturing the metadata keys and values that can appear in data product records associated with the data source, defaults to None

Returns

the updated DataSource record

Raises

AuroraXAPIError

error during API call

AuroraXUnauthorizedError

not allowed to perform task, or API key / user permissions are invalid

AuroraXNotFoundError

data source not found