lazynwb 1.0.0.dev1__tar.gz → 1.0.0.dev2__tar.gz

{lazynwb-1.0.0.dev1/src/lazynwb.egg-info → lazynwb-1.0.0.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lazynwb
-Version: 1.0.0.dev1
+Version: 1.0.0.dev2
 Summary: An attempt to speed-up access to large NWB (Neurodata Without Borders) files stored in the cloud.
 Author-email: Ben Hardcastle <ben.hardcastle@alleninstitue.org>
 License: MIT
@@ -204,6 +204,17 @@ lazynwb.get_internal_paths('my_file.nwb')
 # ['/intervals/trials', '/processing/behavior/running_speed', '/units', ...]
 ```
 
+Use `get` when you want lazynwb to choose the return type from the NWB container:
+```python
+df = lazynwb.get('my_file.nwb', '/units')  # pandas DataFrame by default
+ts = lazynwb.get('my_file.nwb', '/processing/behavior/running_speed', exact_path=True)
+```
+
+Force DataFrame materialization, even for a TimeSeries container:
+```python
+df = lazynwb.get('my_file.nwb', '/processing/behavior/running_speed', exact_path=True, as_df=True)
+```
+
 ---
 
 ## Reading tables
@@ -342,6 +353,13 @@ Get a table as polars:
 df = nwb.get_df('/units', as_polars=True)
 ```
 
+Use the general accessor when you want tables as DataFrames and TimeSeries as
+`TimeSeries` objects:
+```python
+result = nwb.get('/processing/behavior/running_speed', exact_path=True)
+df = nwb.get('/processing/behavior/running_speed', exact_path=True, as_df=True)
+```
+
 Get a summary of everything in the file:
 ```python
 nwb.describe()
@@ -499,10 +517,11 @@ df = lazynwb.get_df('az://my-container/data/file.nwb', '/units')
 df = lazynwb.get_df('https://example.com/data/file.nwb', '/units')
 ```
 
-Configure cloud access via `lazynwb.file_io.config`:
+Configure global defaults via `lazynwb.config`:
 ```python
-from lazynwb.file_io import config
+from lazynwb import config
 
+config.use_polars = True                          # return Polars by default from get_df/get_metadata_df
 config.use_obstore = True                         # use obstore for S3/GCS/Azure (default: False)
 config.use_remfile = False                        # use remfile for HTTP byte-range requests (default: True)
 config.anon = True                                # anonymous access across backends

{lazynwb-1.0.0.dev1 → lazynwb-1.0.0.dev2}/README.md

@@ -156,17 +156,28 @@ import lazynwb
 df = lazynwb.get_df('my_file.nwb', '/intervals/trials')
 ```
 
-Use `get_internal_paths` to find available paths if you're not sure what's in a file:
-```python
-lazynwb.get_internal_paths('my_file.nwb')
-# ['/intervals/trials', '/processing/behavior/running_speed', '/units', ...]
-```
-
----
-
-## Reading tables
-
-### As a pandas or polars DataFrame (`get_df`)
+Use `get_internal_paths` to find available paths if you're not sure what's in a file:
+```python
+lazynwb.get_internal_paths('my_file.nwb')
+# ['/intervals/trials', '/processing/behavior/running_speed', '/units', ...]
+```
+
+Use `get` when you want lazynwb to choose the return type from the NWB container:
+```python
+df = lazynwb.get('my_file.nwb', '/units')  # pandas DataFrame by default
+ts = lazynwb.get('my_file.nwb', '/processing/behavior/running_speed', exact_path=True)
+```
+
+Force DataFrame materialization, even for a TimeSeries container:
+```python
+df = lazynwb.get('my_file.nwb', '/processing/behavior/running_speed', exact_path=True, as_df=True)
+```
+
+---
+
+## Reading tables
+
+### As a pandas or polars DataFrame (`get_df`)
 
 Returns a pandas DataFrame by default:
 ```python
@@ -295,16 +306,23 @@ nwb.subject.strain
 nwb.subject.date_of_birth
 ```
 
-Get a table as polars:
-```python
-df = nwb.get_df('/units', as_polars=True)
-```
-
-Get a summary of everything in the file:
-```python
-nwb.describe()
-# {'identifier': '...', 'session_id': '...', ..., 'paths': ['/acquisition/...', '/units', ...]}
-```
+Get a table as polars:
+```python
+df = nwb.get_df('/units', as_polars=True)
+```
+
+Use the general accessor when you want tables as DataFrames and TimeSeries as
+`TimeSeries` objects:
+```python
+result = nwb.get('/processing/behavior/running_speed', exact_path=True)
+df = nwb.get('/processing/behavior/running_speed', exact_path=True, as_df=True)
+```
+
+Get a summary of everything in the file:
+```python
+nwb.describe()
+# {'identifier': '...', 'session_id': '...', ..., 'paths': ['/acquisition/...', '/units', ...]}
+```
 
 ---
 
@@ -457,16 +475,17 @@ df = lazynwb.get_df('az://my-container/data/file.nwb', '/units')
 df = lazynwb.get_df('https://example.com/data/file.nwb', '/units')
 ```
 
-Configure cloud access via `lazynwb.file_io.config`:
-```python
-from lazynwb.file_io import config
-
-config.use_obstore = True                         # use obstore for S3/GCS/Azure (default: False)
-config.use_remfile = False                        # use remfile for HTTP byte-range requests (default: True)
-config.anon = True                                # anonymous access across backends
-config.fsspec_storage_options = {"request_payer": True}  # backend-specific extras if needed
-config.disable_cache = False                      # disable FileAccessor caching (default: False)
-```
+Configure global defaults via `lazynwb.config`:
+```python
+from lazynwb import config
+
+config.use_polars = True                          # return Polars by default from get_df/get_metadata_df
+config.use_obstore = True                         # use obstore for S3/GCS/Azure (default: False)
+config.use_remfile = False                        # use remfile for HTTP byte-range requests (default: True)
+config.anon = True                                # anonymous access across backends
+config.fsspec_storage_options = {"request_payer": True}  # backend-specific extras if needed
+config.disable_cache = False                      # disable FileAccessor caching (default: False)
+```
 
 For normal AWS S3 buckets, the region belongs to the bucket, not the caller's
 current AWS session. The fast HDF5 range reader discovers and caches bucket

{lazynwb-1.0.0.dev1 → lazynwb-1.0.0.dev2}/pyproject.toml

@@ -24,7 +24,7 @@ dependencies = [
     "aiosqlite>=0.20.0",
     "tomli>=2.0.0; python_version < '3.11'",
 ]
-version = "1.0.0.dev1"
+version = "1.0.0.dev2"
 classifiers = [
     "Development Status :: 3 - Alpha",          # https://pypi.org/classifiers/
     "Programming Language :: Python :: 3",

{lazynwb-1.0.0.dev1 → lazynwb-1.0.0.dev2}/src/lazynwb/__init__.py

@@ -6,11 +6,12 @@ import doctest
 import importlib.metadata
 import logging
 
-import dotenv
-
-from lazynwb.attrs import *
-from lazynwb.base import *
-from lazynwb.conversion import *
+import dotenv
+
+from lazynwb._config import *
+from lazynwb.attrs import *
+from lazynwb.base import *
+from lazynwb.conversion import *
 from lazynwb.dandi import *
 from lazynwb.file_io import *
 from lazynwb.lazyframe import *

lazynwb-1.0.0.dev2/src/lazynwb/_config.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+import pydantic
+import pydantic_settings
+
+logger = logging.getLogger(__name__)
+
+
+class Config(pydantic_settings.BaseSettings):
+    """
+    Global configuration for lazynwb behavior.
+    """
+
+    model_config = pydantic_settings.SettingsConfigDict(
+        env_prefix="",
+        populate_by_name=True,
+    )
+
+    use_polars: bool = pydantic.Field(
+        default=False,
+        validation_alias=pydantic.AliasChoices(
+            "LAZYNWB_USE_POLARS",
+            "LAZYNWB_FILE_IO_USE_POLARS",
+        ),
+    )
+    use_remfile: bool = pydantic.Field(
+        default=True,
+        validation_alias=pydantic.AliasChoices(
+            "LAZYNWB_USE_REMFILE",
+            "LAZYNWB_FILE_IO_USE_REMFILE",
+        ),
+    )
+    use_obstore: bool = pydantic.Field(
+        default=False,
+        validation_alias=pydantic.AliasChoices(
+            "LAZYNWB_USE_OBSTORE",
+            "LAZYNWB_FILE_IO_USE_OBSTORE",
+        ),
+    )
+    anon: bool | None = pydantic.Field(
+        default=None,
+        validation_alias=pydantic.AliasChoices(
+            "LAZYNWB_ANON",
+            "LAZYNWB_FILE_IO_ANON",
+        ),
+    )
+    fsspec_storage_options: dict[str, Any] = pydantic.Field(
+        default_factory=lambda: {"anon": False},
+        validation_alias=pydantic.AliasChoices(
+            "LAZYNWB_FSSPEC_STORAGE_OPTIONS",
+            "LAZYNWB_FILE_IO_FSSPEC_STORAGE_OPTIONS",
+        ),
+    )
+    disable_cache: bool = pydantic.Field(
+        default=False,
+        validation_alias=pydantic.AliasChoices(
+            "LAZYNWB_DISABLE_CACHE",
+            "LAZYNWB_FILE_IO_DISABLE_CACHE",
+        ),
+    )
+
+
+config = Config()
+
+
+def _resolve_as_polars(as_polars: bool | None) -> bool:
+    if as_polars is not None:
+        logger.debug(
+            "using explicit DataFrame backend setting: as_polars=%s", as_polars
+        )
+        return as_polars
+    logger.debug(
+        "using configured DataFrame backend setting: use_polars=%s",
+        config.use_polars,
+    )
+    return config.use_polars
+
+
+__all__ = ["Config", "config"]