+
    }i<9                    Z   ^ RI Ht ^ RIt^ RIHt ^ RIHtHt ^ RIH	t	 ^ RI
Ht ^ RIHt ^ RIHtHt ^R	IHt ^R
IHt ^RIHt ]'       d7   ^ RIHt ^ RIHtHt ^ RIHt ^ RIHtHt ^ RIH t  ^ RI!H"t" ^ RI#H$t$ ^ RI%H&t&H't' ]PP                  ! ])4      t*]! R4       ! R R]4      4       t+R# )    )annotationsN)StringIO)TYPE_CHECKINGoverload)override)service_locator)
docs_group)export_csv_to_streamexport_json_to_stream)Storage)KeyValueStore)validate_storage_name)AsyncIterator)AnyLiteral)Unpack)ExportDataCsvKwargsExportDataJsonKwargs)Configuration)StorageClient)DatasetClient)DatasetItemsListPageDatasetMetadataStoragesc                     ] tR t^ tRtR R lt]]R R l4       4       t]]R R l4       4       t	]R R	 l4       t
]]R
RRRRRRRRR/R R ll4       4       t]R R l4       t]R R l4       tR R ltR^ RRRRRRRRRRR RR!RR"RR#RR$R/R% R& lltR^ RRRRRRRRRRR RR!RR"R/	R' R( lltR^ RRRRRRRRRRR RR!RR"R/	R) R* llt]R2R+ R, ll4       t]R2R- R. ll4       tR3R/ R0 lltR1tR# )4Dataseta  Dataset is a storage for managing structured tabular data.

The dataset class provides a high-level interface for storing and retrieving structured data
with consistent schema, similar to database tables or spreadsheets. It abstracts the underlying
storage implementation details, offering a consistent API regardless of where the data is
physically stored.

Dataset operates in an append-only mode, allowing new records to be added but not modified
or deleted after creation. This makes it particularly suitable for storing crawling results
and other data that should be immutable once collected.

The class provides methods for adding data, retrieving data with various filtering options,
and exporting data to different formats. You can create a dataset using the `open` class method,
specifying either a name or ID. The underlying storage implementation is determined by
the configured storage client.

### Usage

```python
from crawlee.storages import Dataset

# Open a dataset
dataset = await Dataset.open(name='my_dataset')

# Add data
await dataset.push_data({'title': 'Example Product', 'price': 99.99})

# Retrieve filtered data
results = await dataset.get_data(limit=10, desc=True)

# Export data
await dataset.export_to('results.json', content_type='json')
```
c               (    V ^8  d   QhRRRRRRRR/# )	   clientr   idstrname
str | NonereturnNone )formats   "k/Users/ahmad/.openclaw/workspace/my-crawler/.venv/lib/python3.14/site-packages/crawlee/storages/_dataset.py__annotate__Dataset.__annotate__E   s(      } # Z D     c                @    \        V4       Wn        W n        W0n        R# )zInitialize a new instance.

Preferably use the `Dataset.open` constructor to create a new instance.

Args:
    client: An instance of a storage client.
    id: The unique identifier of the storage.
    name: The name of the storage, if available.
N)r   _client_id_name)selfr   r    r"   s   &&&&r(   __init__Dataset.__init__E   s     	d#
r+   c                   V ^8  d   QhRR/# )r   r$   r!   r&   )r'   s   "r(   r)   r*   W   s      C r+   c                	    V P                   # N)r.   r0   s   &r(   r    
Dataset.idU   s     xxr+   c                   V ^8  d   QhRR/# )r   r$   r#   r&   )r'   s   "r(   r)   r*   \   s      j r+   c                	    V P                   # r5   )r/   r6   s   &r(   r"   Dataset.nameZ   s     zzr+   c                   V ^8  d   QhRR/# )r   r$   r   r&   )r'   s   "r(   r)   r*   `   s     1 1O 1r+   c                	R   "   V P                   P                  4       G R j  xL
 #  L5ir5   )r-   get_metadatar6   s   &r(   r=   Dataset.get_metadata_   s     \\..0000s   '%'r    Nr"   aliasconfigurationstorage_clientc               0    V ^8  d   QhRRRRRRRRRRR	R
/# )r   r    r#   r"   r?   r@   Configuration | NonerA   StorageClient | Noner$   r   r&   )r'   s   "r(   r)   r*   e   sH     
 
 
 	

 
 ,
 -
 

r+   c          	     	  "   Vf   \         P                  ! 4       MTpVf   \         P                  ! 4       MTpVP                  WW4R7      pVP	                  VR7      p\         P
                  P                  V VVVVVR7      G R j  xL
 #  L5i)N)r    r"   r?   r@   )r@   )r    r"   r?   client_opener_corostorage_client_cache_key)r   get_configurationget_storage_clientcreate_dataset_clientget_storage_client_cache_keystorage_instance_manageropen_storage_instance)clsr    r"   r?   r@   rA   rF   rG   s   &$$$$$  r(   openDataset.openc   s      @M?T99;ZgAOAW;;=]k+AAE B 
 $2#N#N]j#N#k $==SS1%= T 
 
 	
 
s   BBBBc                   V ^8  d   QhRR/# r   r$   r%   r&   )r'   s   "r(   r)   r*      s     " "D "r+   c                	   "   \         P                  pVP                  V 4       V P                  P	                  4       G R j  xL
  R #  L5ir5   )r   rL   remove_from_cacher-   drop)r0   rL   s   & r(   rU   Dataset.drop   s5     #2#K#K  2248ll!!!s   ?A
AA
c                   V ^8  d   QhRR/# rR   r&   )r'   s   "r(   r)   r*      s     # #T #r+   c                	V   "   V P                   P                  4       G R j  xL
  R #  L5ir5   )r-   purger6   s   &r(   rY   Dataset.purge   s     ll  """s   )')c                    V ^8  d   QhRRRR/# )r   dataz%list[dict[str, Any]] | dict[str, Any]r$   r%   r&   )r'   s   "r(   r)   r*      s     0 0$I 0d 0r+   c                Z   "   V P                   P                  VR7      G Rj  xL
  R#  L5i)a  Store an object or an array of objects to the dataset.

The size of the data is limited by the receiving API and therefore `push_data()` will only
allow objects whose JSON representation is smaller than 9MB. When an array is passed,
none of the included objects may be larger than 9MB, but the array itself may be of any size.

Args:
    data: A JSON serializable data structure to be stored in the dataset. The JSON representation
        of each item must be smaller than 9MB.
)r\   N)r-   	push_data)r0   r\   s   &&r(   r^   Dataset.push_data   s"      ll$$$$///s    +)+offsetlimitl   J)cleanFdescfieldsomitunwind
skip_emptyskip_hiddenflattenviewc               H    V ^8  d   QhRRRRRRRRRR	R
R	RR	RRRRRR	RRRR/# )r   r`   intra   
int | Nonerb   boolrc   rd   list[str] | Nonere   rf   rg   rh   ri   rj   r#   r$   r   r&   )r'   s   "r(   r)   r*      s     1
 1
 1
 	1

 1
 1
 !1
 1
 !1
 1
 1
 "1
 1
 
1
r+   c               j   "   V P                   P                  VVVVVVVVV	V
VR7      G Rj  xL
 #  L5i)a  Retrieve a paginated list of items from a dataset based on various filtering parameters.

This method provides the flexibility to filter, sort, and modify the appearance of dataset items
when listed. Each parameter modifies the result set according to its purpose. The method also
supports pagination through 'offset' and 'limit' parameters.

Args:
    offset: Skips the specified number of items at the start.
    limit: The maximum number of items to retrieve. Unlimited if None.
    clean: Return only non-empty items and excludes hidden fields. Shortcut for skip_hidden and skip_empty.
    desc: Set to True to sort results in descending order.
    fields: Fields to include in each item. Sorts fields as specified if provided.
    omit: Fields to exclude from each item.
    unwind: Unwinds items by a specified array field, turning each element into a separate item.
    skip_empty: Excludes empty items from the results if True.
    skip_hidden: Excludes fields starting with '#' if True.
    flatten: Fields to be flattened in returned items.
    view: Specifies the dataset view to be used.

Returns:
    An object with filtered, sorted, and paginated dataset items plus pagination details.
)r`   ra   rb   rc   rd   re   rf   rg   rh   ri   rj   N)r-   get_data)r0   r`   ra   rb   rc   rd   re   rf   rg   rh   ri   rj   s   &$$$$$$$$$$$r(   rq   Dataset.get_data   sO     J \\**!# + 
 
 	
 
s   *313c               @    V ^8  d   QhRRRRRRRRRR	R
R	RR	RRRRRR/
# )r   r`   rl   ra   rm   rb   rn   rc   rd   ro   re   rf   rg   rh   r$   zAsyncIterator[dict[str, Any]]r&   )r'   s   "r(   r)   r*      sp     . . . 	.
 . . !. . !. . . 
'.r+   c       	       ~   "   V P                   P                  VVVVVVVVV	R7	        Rj  xL
  p
V
5x  K   LDR# 5i)a  Iterate over items in the dataset according to specified filters and sorting.

This method allows for asynchronously iterating through dataset items while applying various filters such as
skipping empty items, hiding specific fields, and sorting. It supports pagination via `offset` and `limit`
parameters, and can modify the appearance of dataset items using `fields`, `omit`, `unwind`, `skip_empty`, and
`skip_hidden` parameters.

Args:
    offset: Skips the specified number of items at the start.
    limit: The maximum number of items to retrieve. Unlimited if None.
    clean: Return only non-empty items and excludes hidden fields. Shortcut for skip_hidden and skip_empty.
    desc: Set to True to sort results in descending order.
    fields: Fields to include in each item. Sorts fields as specified if provided.
    omit: Fields to exclude from each item.
    unwind: Unwinds items by a specified array field, turning each element into a separate item.
    skip_empty: Excludes empty items from the results if True.
    skip_hidden: Excludes fields starting with '#' if True.

Yields:
    An asynchronous iterator of dictionary objects, each representing a dataset item after applying
    the specified filters and transformations.
	r`   ra   rb   rc   rd   re   rf   rg   rh   N)r-   iterate_itemsr0   r`   ra   rb   rc   rd   re   rf   rg   rh   items   &$$$$$$$$$ r(   rv   Dataset.iterate_items   sW     F ,,44!# 5 

 	 	$ J	 

s   %=:8:	=:=c               @    V ^8  d   QhRRRRRRRRRR	R
R	RR	RRRRRR/
# )r   r`   rl   ra   rm   rb   rn   rc   rd   ro   re   rf   rg   rh   r$   zlist[dict[str, Any]]r&   )r'   s   "r(   r)   r*      sp     0
 0
 0
 	0

 0
 0
 !0
 0
 !0
 0
 0
 
0
r+   c       	        v   "   V P                  VVVVVVVVV	R7	       U
u. u Rj  xL
 p
V
NK   LD	up
# u up
i 5i)a  Retrieve a list of all items from the dataset according to specified filters and sorting.

This method collects all dataset items into a list while applying various filters such as
skipping empty items, hiding specific fields, and sorting. It supports pagination via `offset` and `limit`
parameters, and can modify the appearance of dataset items using `fields`, `omit`, `unwind`, `skip_empty`, and
`skip_hidden` parameters.

Args:
    offset: Skips the specified number of items at the start.
    limit: The maximum number of items to retrieve. Unlimited if None.
    clean: Return only non-empty items and excludes hidden fields. Shortcut for skip_hidden and skip_empty.
    desc: Set to True to sort results in descending order.
    fields: Fields to include in each item. Sorts fields as specified if provided.
    omit: Fields to exclude from each item.
    unwind: Unwinds items by a specified array field, turning each element into a separate item.
    skip_empty: Excludes empty items from the results if True.
    skip_hidden: Excludes fields starting with '#' if True.

Returns:
    A list of dictionary objects, each representing a dataset item after applying
    the specified filters and transformations.
ru   N)rv   rw   s   &$$$$$$$$$ r(   
list_itemsDataset.list_items   sX     J #00%' 1 

 
 
 	
 
s$   940.
04049c               8    V ^8  d   QhRRRRRRRRRR	R
RRRRR/# )r   keyr!   content_typezLiteral['json']	to_kvs_idr#   to_kvs_nameto_kvs_storage_clientrD   to_kvs_configurationrC   kwargszUnpack[ExportDataJsonKwargs]r$   r%   r&   )r'   s   "r(   r)   r*   ,  sZ     	 		 &	 		
  	  4	 3	 /	 
	r+   c                	   "   R # 5ir5   r&   r0   r   r   r   r   r   r   r   s   &&&&&&&,r(   	export_toDataset.export_to+  
         c               8    V ^8  d   QhRRRRRRRRRR	R
RRRRR/# )r   r   r!   r   zLiteral['csv']r   r#   r   r   rD   r   rC   r   zUnpack[ExportDataCsvKwargs]r$   r%   r&   )r'   s   "r(   r)   r*   8  sZ     	 		 %	 		
  	  4	 3	 .	 
	r+   c                	   "   R # 5ir5   r&   r   s   &&&&&&&,r(   r   r   7  r   r   c               8    V ^8  d   QhRRRRRRRRRR	R
RRRRR/# )r   r   r!   r   zLiteral['json', 'csv']r   r#   r   r   rD   r   rC   r   r   r$   r%   r&   )r'   s   "r(   r)   r*   C  sd     +P +P+P -+P 	+P
  +P  4+P 3+P +P 
+Pr+   c                  "   \         P                  ! VVVVR7      G Rj  xL
 p\        4       p	VR8X  dN   \        V P	                  4       V	3/ VB G Rj  xL
  VP                  WP                  4       R4      G Rj  xL
  R# VR8X  dN   \        V P	                  4       V	3/ VB G Rj  xL
  VP                  WP                  4       R4      G Rj  xL
  R# \        R4      h L L Li L? L5i)a  Export the entire dataset into a specified file stored under a key in a key-value store.

This method consolidates all entries from a specified dataset into one file, which is then saved under a
given key in a key-value store. The format of the exported file is determined by the `content_type` parameter.
Either the dataset's ID or name should be specified, and similarly, either the target key-value store's ID or
name should be used.

Args:
    key: The key under which to save the data in the key-value store.
    content_type: The format in which to export the data.
    to_kvs_id: ID of the key-value store to save the exported file.
        Specify only one of ID or name.
    to_kvs_name: Name of the key-value store to save the exported file.
        Specify only one of ID or name.
    to_kvs_storage_client: Storage client to use for the key-value store.
    to_kvs_configuration: Configuration for the key-value store.
    kwargs: Additional parameters for the export operation, specific to the chosen content type.
)r    r"   r@   rA   Ncsvztext/csvjsonzapplication/jsonz/Unsupported content type, expecting CSV or JSON)	r   rO   r   r
   rv   	set_valuegetvaluer   
ValueError)
r0   r   r   r   r   r   r   r   kvsdsts
   &&&&&&&,  r(   r   r   C  s     8 "&&.0	
 
 j5 &t'9'9';SKFKKK--\\^Z@@@V#'(:(:(<cLVLLL--\\^5GHHHNOO
 L@LHsW   C,C"3C,C$'C,<C&=+C,(C()'C,C*C,$C,&C,(C,*C,)r-   r.   r/   )NNNN)r   NNNN)__name__
__module____qualname____firstlineno____doc__r1   propertyr   r    r"   r=   classmethodrO   rU   rY   r^   rq   rv   r|   r   r   __static_attributes__r&   r+   r(   r   r       s<   !F        1 1 
 
  	

 !
 /3
 04
  
4 " "
 # #01
 1
 ,	1

 1
 1
 $(1
 "&1
 $(1
 !1
 "1
 %)1
  1
f. . ,	.
 . . $(. "&. $(. !. ".`0
 0
 ,	0

 0
 0
 $(0
 "&0
 $(0
 !0
 "0
d 	 	 	 	+P +Pr+   r   ),
__future__r   loggingior   typingr   r   typing_extensionsr   crawleer   crawlee._utils.docsr	   crawlee._utils.filer
   r   _baser   _key_value_storer   _utilsr   collections.abcr   r   r   r   crawlee._typesr   r   crawlee.configurationr   crawlee.storage_clientsr   crawlee.storage_clients._baser   crawlee.storage_clients.modelsr   r   	getLoggerr   loggerr   r&   r+   r(   <module>r      sw    "   * & # * K  + )-#(H35;T			8	$ JMPg MP MPr+   