
    <i_                         S r SSKJrJr  SSKrSSKJrJr  SSKJ	r	  S r
 " S S\5      r " S	 S
\5      r " S S\S9r " S S\S9r " S S\5      rg)zv
Python STIX2 DataStore API.

.. autosummary::
   :toctree: datastore

   filesystem
   filters
   memory
   taxii

|
    )ABCMetaabstractmethodN)Filter	FilterSet)deduplicatec                  >    [        [        R                  " 5       5      $ N)struuiduuid4     R/home/james-whalen/.local/lib/python3.13/site-packages/stix2/datastore/__init__.pymake_idr      s    tzz|r   c                   (    \ rS rSrSrSS jrS rSrg)DataSourceError   a  General DataSource error instance, used primarily for wrapping
lower level errors

Args:
    message (str): error message
    root_exception (Exception): Exception instance of root exception
        in the case that DataSourceError is wrapping a lower level or
        other exception
Nc                     Xl         X l        g r	   messageroot_exception)selfr   r   s      r   __init__DataSourceError.__init__$   s    ,r   c                     U R                   (       a&  SR                  U R                  U R                   5      $ U R                  $ )Nz{} "{}")r   formatr   r   s    r   __str__DataSourceError.__str__(   s2    %%dllD4G4GHH<<r   r   r	   )__name__
__module____qualname____firstlineno____doc__r   r   __static_attributes__r   r   r   r   r      s    - r   r   c                   Z   ^  \ rS rSrSrSU 4S jjrS rS rS rS r	S r
S	 rS
 rSrU =r$ )DataStoreMixin/   a  Provides mechanisms for storing and retrieving STIX data. The specific
behavior can be customized by subclasses.

Args:
    source (DataSource): An existing DataSource to use
        as this DataStore's DataSource component
    sink (DataSink): An existing DataSink to use
        as this DataStore's DataSink component

Attributes:
    id (str): A unique UUIDv4 to identify this DataStore.
    source (DataSource): An object that implements DataSource class.
    sink (DataSink): An object that implements DataSink class.

c                 `   > [         [        U ]  5         [        5       U l        Xl        X l        g r	   )superr'   r   r   idsourcesink)r   r,   r-   	__class__s      r   r   DataStoreMixin.__init__?   s#    nd,.)	r   c                      U R                   R                  " U0 UD6$ ! [         a$    Sn[        X0R                  R                  -  5      ef = f)a%  Retrieve the most recent version of a single STIX object by ID.

Translate get() call to the appropriate DataSource call.

Args:
    stix_id (str): the id of the STIX object to retrieve.

Returns:
    stix_obj: the single most recent version of the STIX
        object specified by the "id".

%s has no data source to query)r,   getAttributeErrorr.   r    r   argskwargsmsgs       r   r2   DataStoreMixin.getE   sN    	@;;??D3F33 	@2C ~~'>'>!>??	@	    .Ac                      U R                   R                  " U0 UD6$ ! [         a$    Sn[        X0R                  R                  -  5      ef = f)zRetrieve all versions of a single STIX object by ID.

Translate all_versions() call to the appropriate DataSource call.

Args:
    stix_id (str): the id of the STIX object to retrieve.

Returns:
    list: All versions of the specified STIX object.

r1   )r,   all_versionsr3   r.   r    r4   s       r   r;   DataStoreMixin.all_versionsX   sP    	@;;++T<V<< 	@2C ~~'>'>!>??	@r9   c                      U R                   R                  " U0 UD6$ ! [         a$    Sn[        X0R                  R                  -  5      ef = f)a  Retrieve STIX objects matching a set of filters.

Translate query() call to the appropriate DataSource call.

Args:
    query (list): a list of filters (which collectively are the query)
        to conduct search on.

Returns:
    list: The STIX objects matching the query.

r1   )r,   queryr3   r.   r    r4   s       r   r>   DataStoreMixin.queryj   sP    	@;;$$d5f55 	@2C ~~'>'>!>??	@r9   c                      U R                   R                  " U0 UD6$ ! [         a$    Sn[        X0R                  R                  -  5      ef = f)as  Retrieve the Identity refered to by the object's `created_by_ref`.

Translate creator_of() call to the appropriate DataSource call.

Args:
    obj: The STIX object whose `created_by_ref` property will be looked
        up.

Returns:
    The STIX object's creator, or None, if the object contains no
    `created_by_ref` property or the object's creator cannot be found.

r1   )r,   
creator_ofr3   r.   r    r4   s       r   rA   DataStoreMixin.creator_of}   sP    	@;;))4:6:: 	@2C ~~'>'>!>??	@r9   c                      U R                   R                  " U0 UD6$ ! [         a$    Sn[        X0R                  R                  -  5      ef = f)a  Retrieve Relationships involving the given STIX object.

Translate relationships() call to the appropriate DataSource call.

Only one of `source_only` and `target_only` may be `True`.

Args:
    obj (STIX object OR dict OR str): The STIX object (or its ID) whose
        relationships will be looked up.
    relationship_type (str): Only retrieve Relationships of this type.
        If None, all relationships will be returned, regardless of type.
    source_only (bool): Only retrieve Relationships for which this
        object is the source_ref. Default: False.
    target_only (bool): Only retrieve Relationships for which this
        object is the target_ref. Default: False.

Returns:
    list: The Relationship objects involving the given STIX object.

r1   )r,   relationshipsr3   r.   r    r4   s       r   rD   DataStoreMixin.relationships   sP    *	@;;,,d=f== 	@2C ~~'>'>!>??	@r9   c                      U R                   R                  " U0 UD6$ ! [         a$    Sn[        X0R                  R                  -  5      ef = f)ax  Retrieve STIX Objects that have a Relationship involving the given
STIX object.

Translate related_to() call to the appropriate DataSource call.

Only one of `source_only` and `target_only` may be `True`.

Args:
    obj (STIX object OR dict OR str): The STIX object (or its ID) whose
        related objects will be looked up.
    relationship_type (str): Only retrieve objects related by this
        Relationships type. If None, all related objects will be
        returned, regardless of type.
    source_only (bool): Only examine Relationships for which this
        object is the source_ref. Default: False.
    target_only (bool): Only examine Relationships for which this
        object is the target_ref. Default: False.
    filters (list): list of additional filters the related objects must
        match.

Returns:
    list: The STIX objects related to the given STIX object.

r1   )r,   
related_tor3   r.   r    r4   s       r   rG   DataStoreMixin.related_to   sP    2	@;;))4:6:: 	@2C ~~'>'>!>??	@r9   c                      U R                   R                  " U0 UD6$ ! [         a$    Sn[        X0R                  R                  -  5      ef = f)zMethod for storing STIX objects.

Defines custom behavior before storing STIX objects using the
appropriate method call on the associated DataSink.

Args:
    stix_objs (list): a list of STIX objects

z%%s has no data sink to put objects in)r-   addr3   r.   r    r4   s       r   rJ   DataStoreMixin.add   sN    	@99==$1&11 	@9C ~~'>'>!>??	@r9   )r+   r-   r,   NN)r    r!   r"   r#   r$   r   r2   r;   r>   rA   rD   rG   rJ   r%   __classcell__r.   s   @r   r'   r'   /   s=    @&@$@&@(@6@>@ @r   r'   c                   <   ^  \ rS rSrSrU 4S jr\S 5       rSrU =r	$ )DataSink   zAn implementer will create a concrete subclass from
this class for the specific DataSink.

Attributes:
    id (str): A unique UUIDv4 to identify this DataSink.

c                 H   > [         [        U ]  5         [        5       U l        g r	   )r*   rP   r   r   r+   r   r.   s    r   r   DataSink.__init__   s    h&()r   c                     g)zMethod for storing STIX objects.

Implement: Specific data sink API calls, processing,
functionality required for adding data to the sink

Args:
    stix_objs (list): a list of STIX objects (where each object is a
        STIX object)

Nr   )r   	stix_objss     r   rJ   DataSink.add       r   )r+   )
r    r!   r"   r#   r$   r   r   rJ   r%   rM   rN   s   @r   rP   rP      s!     
 
r   rP   )	metaclassc                   z   ^  \ rS rSrSrU 4S jr\S 5       r\S 5       r\SS j5       r	S r
SS jrSS	 jrS
rU =r$ )
DataSource   zAn implementer will create a concrete subclass from
this class for the specific DataSource.

Attributes:
    id (str): A unique UUIDv4 to identify this DataSource.
    filters (FilterSet): A collection of filters attached to this DataSource.

c                 f   > [         [        U ]  5         [        5       U l        [        5       U l        g r	   )r*   r[   r   r   r+   r   filtersrS   s    r   r   DataSource.__init__   s"    j$(*) {r   c                     g)aS  
Implement: Specific data source API calls, processing,
functionality required for retrieving data from the data source

Args:
    stix_id (str): the id of the STIX 2.0 object to retrieve. Should
        return a single object, the most recent version of the object
        specified by the "id".

Returns:
    stix_obj: The STIX object.

Nr   r   stix_ids     r   r2   DataSource.get  rX   r   c                     g)a  
Implement: Similar to get() except returns list of all object versions
of the specified "id". In addition, implement the specific data
source API calls, processing, functionality required for retrieving
data from the data source.

Args:
    stix_id (str): The id of the STIX 2.0 object to retrieve. Should
        return a list of objects, all the versions of the object
        specified by the "id".

Returns:
    list: All versions of the specified STIX object.

Nr   ra   s     r   r;   DataSource.all_versions  rX   r   c                     g)a'  
Implement: The specific data source API calls, processing,
functionality required for retrieving query from the data source

Args:
    query (list): a list of filters (which collectively are the query)
        to conduct search on.

Returns:
    list: The STIX objects that matched the query.

Nr   )r   r>   s     r   r>   DataSource.query&  rX   r   c                 X    UR                  SS5      nU(       a  U R                  U5      $ g)a3  Retrieve the Identity referred to by the object's `created_by_ref`.

Args:
    obj: The STIX object whose `created_by_ref` property will be looked
        up.

Returns:
    The STIX object's creator, or None, if the object contains no
    `created_by_ref` property or the object's creator cannot be found.

created_by_ref N)r2   )r   obj
creator_ids      r   rA   DataSource.creator_of5  s*     WW-r2
88J''r   c           
         / n[        SSS5      /n US   nU(       a  UR	                  [        SSU5      5        U(       a  U(       a  [        S5      eU(       d/  UR                  U R                  U[        SSU5      /-   5      5        U(       d/  UR                  U R                  U[        S	SU5      /-   5      5        U$ ! [         a    [        S5      e[         a    Un Nf = f)
a  Retrieve Relationships involving the given STIX object.

Only one of `source_only` and `target_only` may be `True`.

Args:
    obj (STIX object OR dict OR str): The STIX object (or its ID) whose
        relationships will be looked up.
    relationship_type (str): Only retrieve Relationships of this type.
        If None, all relationships will be returned, regardless of type.
    source_only (bool): Only retrieve Relationships for which this
        object is the source_ref. Default: False.
    target_only (bool): Only retrieve Relationships for which this
        object is the target_ref. Default: False.

Returns:
    list: The Relationship objects involving the given STIX object.

type=relationshipr+   z STIX object has no 'id' propertyrelationship_typez6Search either source only or target only, but not both
source_ref
target_ref)r   KeyError
ValueError	TypeErrorappendextendr>   )r   rk   rr   source_onlytarget_onlyresultsr^   obj_ids           r   rD   DataSource.relationshipsG  s    & &#~67	YF NN6"5s<MNO;UVVNN4::gc61R0S&STUNN4::gc61R0S&STU#  	A?@@ 	F	s   C  C$#C$c                    / nU R                  XX45      n US   n[        5       n	U H*  n
U	R                  U
R                  U
R
                  45        M,     U	R                  U5        [        U5      nU	 HB  nUR                  U R                  U Vs/ s H  oPM     sn[        SSU5      /-   5      5        MD     U$ ! [         a    Un Nf = fs  snf )a7  Retrieve STIX Objects that have a Relationship involving the given
STIX object.

Only one of `source_only` and `target_only` may be `True`.

Args:
    obj (STIX object OR dict OR str): The STIX object (or its ID) whose
        related objects will be looked up.
    relationship_type (str): Only retrieve objects related by this
        Relationships type. If None, all related objects will be
        returned, regardless of type.
    source_only (bool): Only examine Relationships for which this
        object is the source_ref. Default: False.
    target_only (bool): Only examine Relationships for which this
        object is the target_ref. Default: False.
    filters (list): list of additional filters the related objects must
        match.

Returns:
    list: The STIX objects related to the given STIX object.

r+   rp   )rD   rw   setupdaters   rt   discardr   ry   r>   r   )r   rk   rr   rz   r{   r^   r|   relsr}   idsrfilter_listifs                 r   rG   DataSource.related_tor  s    . !!#+S	YF eAJJall34 F  (ANN4::+&>+Qq+&>&sTUBVAW&WXY  !  	F	 '?s   B; C;C
	C
)r^   r+   r	   )NFF)NFFN)r    r!   r"   r#   r$   r   r   r2   r;   r>   rA   rD   rG   r%   rM   rN   s   @r   r[   r[      s^    #
    "  $)V, ,r   r[   c                   z   ^  \ rS rSrSrU 4S jrSS jrSS jrSS jrS r	S r
S	 rS
 rS rS rS rS rSrU =r$ )CompositeDataSourcei  a  Controller for all the attached DataSources.

A user can have a single CompositeDataSource as an interface
to a set of DataSources. When an API call is made to the
CompositeDataSource, it is delegated to each of the (real)
DataSources that are attached to it.

DataSources can be attached to CompositeDataSource for a variety
of reasons, e.g. common filters, organization, less API calls.

Attributes:

    data_sources (list): A dictionary of DataSource objects; to be
        controlled and used by the Data Source Controller object.

c                 8   > [         [        U ]  5         / U l        g)z'Create a new STIX Data Source.

Args:

N)r*   r   r   data_sourcesrS   s    r   r   CompositeDataSource.__init__  s     	!413r   c                    U R                  5       (       d  [        S5      e/ n[        5       nUR                  U R                  5        U(       a  UR                  U5        U R
                   H,  nUR                  XS9nU(       d  M  UR                  U5        M.     S=pxU H=  n	U	R                  S5      =(       d    U	R                  S5      n
Ub
  U
b  X:  d  M9  U	nU
nM?     U$ )a  Retrieve STIX object by STIX ID

Federated retrieve method, iterates through all DataSources
defined in the "data_sources" parameter. Each data source has a
specific API retrieve-like function and associated parameters. This
function does a federated retrieval and consolidation of the data
returned from all the STIX data sources.

A composite data source will pass its attached filters to
each configured data source, pushing filtering to them to handle.

Args:
    stix_id (str): the id of the STIX object to retrieve.
    _composite_filters (FilterSet): a collection of filters passed from a
        CompositeDataSource (i.e. if this CompositeDataSource is attached
        to another parent CompositeDataSource), not user supplied.

Returns:
    stix_obj: The STIX object to be returned.

'CompositeDataSource has no data sourcesrb   _composite_filtersNmodifiedcreated)has_data_sourcesr3   r   rJ   r^   r   r2   rx   )r   rb   r   all_dataall_filtersdsdatastix_obj
latest_verrk   vers              r   r2   CompositeDataSource.get  s    , $$&& !JKKk%OO./ ##B66'6JDt% $ !%$C''*%;);C3;#2B 
  r   c                 ^   U R                  5       (       d  [        S5      e/ n[        5       nUR                  U R                  5        U(       a  UR                  U5        U R
                   H#  nUR                  XS9nUR                  U5        M%     [        U5      S:  a  [        U5      nU$ )ag  Retrieve all versions of a STIX object by STIX ID.

Federated all_versions retrieve method - iterates through all
DataSources defined in "data_sources".

A composite data source will pass its attached filters to
each configured data source, pushing filtering to them to handle.

Args:
    stix_id (str): id of the STIX objects to retrieve.
    _composite_filters (FilterSet): a collection of filters passed from a
        CompositeDataSource (i.e. if this CompositeDataSource is
        attached to a parent CompositeDataSource), not user supplied.

Returns:
    list: The STIX objects that have the specified id.

r   r   r   )
r   r3   r   rJ   r^   r   r;   ry   lenr   )r   rb   r   r   r   r   r   s          r   r;    CompositeDataSource.all_versions  s    & $$&& !JKKk%OO./ ##B??7?SDOOD! $ x=1"8,Hr   c                 p   U R                  5       (       d  [        S5      eU(       d  / n/ n[        5       nUR                  U R                  5        U(       a  UR                  U5        U R
                   H#  nUR                  XS9nUR                  U5        M%     [        U5      S:  a  [        U5      nU$ )a  Retrieve STIX objects that match a query.

Federate the query to all DataSources attached to the
Composite Data Source.

Args:
    query (list): list of filters to search on.
    _composite_filters (FilterSet): a collection of filters passed from a
        CompositeDataSource (i.e. if this CompositeDataSource is
        attached to a parent CompositeDataSource), not user supplied.

Returns:
    list: The STIX objects to be returned.

r   )r>   r   r   )
r   r3   r   rJ   r^   r   r>   ry   r   r   )r   r>   r   r   r   r   r   s          r   r>   CompositeDataSource.query  s      $$&& !JKK Ek%OO./ ##B88%8HDOOD! $ x=1"8,Hr   c                     U R                  5       (       d  [        S5      e/ nU R                   H$  nUR                  UR                  " U0 UD65        M&     [        U5      S:  a  [        U5      nU$ )a  Retrieve Relationships involving the given STIX object.

Only one of `source_only` and `target_only` may be `True`.

Federated relationships retrieve method - iterates through all
DataSources defined in "data_sources".

Args:
    obj (STIX object OR dict OR str): The STIX object (or its ID) whose
        relationships will be looked up.
    relationship_type (str): Only retrieve Relationships of this type.
        If None, all relationships will be returned, regardless of type.
    source_only (bool): Only retrieve Relationships for which this
        object is the source_ref. Default: False.
    target_only (bool): Only retrieve Relationships for which this
        object is the target_ref. Default: False.

Returns:
    list: The Relationship objects involving the given STIX object.

r   r   )r   r3   r   ry   rD   r   r   r   r5   r6   r|   r   s        r   rD   !CompositeDataSource.relationshipsD  sm    , $$&& !JKK##BNN2++T<V<= $
 w<!!'*Gr   c                     U R                  5       (       d  [        S5      e/ nU R                   H$  nUR                  UR                  " U0 UD65        M&     [        U5      S:  a  [        U5      nU$ )a  Retrieve STIX Objects that have a Relationship involving the given
STIX object.

Only one of `source_only` and `target_only` may be `True`.

Federated related objects method - iterates through all
DataSources defined in "data_sources".

Args:
    obj (STIX object OR dict OR str): The STIX object (or its ID) whose
        related objects will be looked up.
    relationship_type (str): Only retrieve objects related by this
        Relationships type. If None, all related objects will be
        returned, regardless of type.
    source_only (bool): Only examine Relationships for which this
        object is the source_ref. Default: False.
    target_only (bool): Only examine Relationships for which this
        object is the target_ref. Default: False.
    filters (list): list of additional filters the related objects must
        match.

Returns:
    list: The STIX objects related to the given STIX object.

r   r   )r   r3   r   ry   rG   r   r   r   s        r   rG   CompositeDataSource.related_toh  sk    4 $$&& !JKK##BNN2==$9&9: $
 w<!!'*Gr   c                    [        UR                  [        5      (       aP  UR                  U R                   Vs/ s H  o"R                  PM     sn;  a  U R                  R                  U5        g[        S[        U5      -  5      es  snf )zAttach a DataSource to CompositeDataSource instance

Args:
    data_source (DataSource): a stix2.DataSource to attach
        to the CompositeDataSource

zQDataSource (to be added) is not of type stix2.DataSource. DataSource type is '%s'N)
issubclassr.   r[   r+   r   rx   rw   ro   )r   data_sourceds_s      r   add_data_source#CompositeDataSource.add_data_source  s     k++Z88~~8I8I%J8Iff8I%JJ!!((5 	 orv  xC  sD  D  E  E	 &Ks   Bc                 8    U H  nU R                  U5        M     g)zAttach list of DataSources to CompositeDataSource instance

Args:
    data_sources (list): stix2.DataSources to attach to
        CompositeDataSource
N)r   )r   r   r   s      r   add_data_sources$CompositeDataSource.add_data_sources  s     B  $ r   c                     S nU R                    Vs/ s H  o2" UR                  U5      (       a  M  UPM      snU R                   SS& gs  snf )zjRemove DataSource from the CompositeDataSource instance

Args:
    data_source_id (str): DataSource IDs.

c                 
    X:H  $ r	   r   )ds_idcandidate_ds_ids     r   _match6CompositeDataSource.remove_data_source.<locals>._match  s    ++r   N)r   r+   )r   data_source_idr   r   s       r   remove_data_source&CompositeDataSource.remove_data_source  sG    	, .2->->d->rfRUUTbFc->d!  es
   AAc                 8    U H  nU R                  U5        M     g)zlRemove DataSources from the CompositeDataSource instance

Args:
    data_source_ids (list): DataSource IDs

N)r   )r   data_source_idsr   s      r   remove_data_sources'CompositeDataSource.remove_data_sources  s     %E##E* %r   c                 ,    [        U R                  5      $ r	   )r   r   r   s    r   r   $CompositeDataSource.has_data_sources  s    4$$%%r   c                     U R                   $ r	   r   r   s    r   get_all_data_sources(CompositeDataSource.get_all_data_sources  s       r   r   r	   rL   )r    r!   r"   r#   r$   r   r2   r;   r>   rD   rG   r   r   r   r   r   r   r%   rM   rN   s   @r   r   r     sN     0d(T+Z"H&P"		&! !r   r   )r$   abcr   r   r   stix2.datastore.filtersr   r   stix2.utilsr   r   	Exceptionr   objectr'   rP   r[   r   r   r   r   <module>r      sc    (  5 # i  *j@V j@Z 4h7 hVh!* h!r   