Merge pull request #24 from openscm/more-accessors

More accessors

Author: znicholls

changelog/24.breaking.md

@@ -0,0 +1,4 @@
+- Renamed pandas_openscm.register_pandas_accessor to [pandas_openscm.register_pandas_accessors][] (with a trailing 's') as accessors are now also registered for [pandas Series][pandas.Series]
+- Renamed pandas_openscm.accessors.DataFramePandasOpenSCMAccessor to [pandas_openscm.accessors.PandasDataFrameOpenSCMAccessor][]
+- Renamed `df_unit_level` to `unit_level` in [pandas_openscm.accessors.PandasDataFrameOpenSCMAccessor.convert_unit_like][]
+- Renamed `df` to `pobj` in [pandas_openscm.index_manipulation.set_index_levels_func][], [pandas_openscm.unit_conversion.convert_unit_from_target_series][], [pandas_openscm.unit_conversion.convert_unit][] and [pandas_openscm.unit_conversion.convert_unit_like][]

changelog/24.feature.md

@@ -0,0 +1 @@
+Added some accessors for [pandas Series][pandas.Series] via [pandas_openscm.accessors.PandasSeriesOpenSCMAccessor][]. Note that this is not feature complete yet, tracking in [#25](https://github.com/openscm/pandas-openscm/issues/25)

changelog/24.improvement.md

@@ -0,0 +1 @@
+[pandas_openscm.index_manipulation.set_index_levels_func][], [pandas_openscm.unit_conversion.convert_unit_from_target_series][], [pandas_openscm.unit_conversion.convert_unit][] and [pandas_openscm.unit_conversion.convert_unit_like][] now explicitly support [pd.Series][pandas.Series]

changelog/24.trivial.md

@@ -0,0 +1 @@
+Added [pandas_openscm.testing.convert_to_desired_type] and [pandas_openscm.testing.check_result] to help with testing support for [pd.DataFrame][pandas.DataFrame] and [pd.Series][pandas.Series]

docs/changelog.md

@@ -25,8 +25,8 @@ from the examples given in that link.
 
 ### 🆕 Features
 
-- - Added unit conversion APIs: [pandas_openscm.unit_conversion.convert_unit] and [pandas_openscm.unit_conversion.convert_unit_like] and the corresponding accessors [pandas_openscm.accessors.DataFramePandasOpenSCMAccessor.convert_unit] and [pandas_openscm.accessors.DataFramePandasOpenSCMAccessor.convert_unit_like]
-  - Added the helper: [pandas_openscm.index_manipulation.ensure_is_multiindex] and the corresponding accessors [pandas_openscm.accessors.DataFramePandasOpenSCMAccessor.ensure_index_is_multiindex] and [pandas_openscm.accessors.DataFramePandasOpenSCMAccessor.eiim]
+- - Added unit conversion APIs: [pandas_openscm.unit_conversion.convert_unit] and [pandas_openscm.unit_conversion.convert_unit_like] and the corresponding accessors [pandas_openscm.accessors.PandasDataFrameOpenSCMAccessor.convert_unit] and [pandas_openscm.accessors.PandasDataFrameOpenSCMAccessor.convert_unit_like]
+  - Added the helper: [pandas_openscm.index_manipulation.ensure_is_multiindex] and the corresponding accessors [pandas_openscm.accessors.PandasDataFrameOpenSCMAccessor.ensure_index_is_multiindex] and [pandas_openscm.accessors.PandasDataFrameOpenSCMAccessor.eiim]
 
   ([#23](https://github.com/openscm/pandas-openscm/pull/23))
 
@@ -46,7 +46,7 @@ from the examples given in that link.
 
 ### 🆕 Features
 
-- Added [pandas_openscm.index_manipulation.set_levels][] and the corresponding accessor [pandas_openscm.accessors.DataFramePandasOpenSCMAccessor.set_index_levels][] ([#18](https://github.com/openscm/pandas-openscm/pull/18))
+- Added [pandas_openscm.index_manipulation.set_levels][] and the corresponding accessor [pandas_openscm.accessors.PandasDataFrameOpenSCMAccessor.set_index_levels][] ([#18](https://github.com/openscm/pandas-openscm/pull/18))
 
 
 ## Pandas-OpenSCM v0.5.0 (2025-05-10)
@@ -84,7 +84,7 @@ from the examples given in that link.
 ### 🆕 Features
 
 - Add compare_close function to compare two dataframes. ([#16](https://github.com/openscm/pandas-openscm/pull/16))
-- Added [pandas_openscm.index_manipulation.update_levels_from_other][] and the corresponding accessor [pandas_openscm.accessors.DataFramePandasOpenSCMAccessor.update_index_levels_from_other][] ([#17](https://github.com/openscm/pandas-openscm/pull/17))
+- Added [pandas_openscm.index_manipulation.update_levels_from_other][] and the corresponding accessor [pandas_openscm.accessors.PandasDataFrameOpenSCMAccessor.update_index_levels_from_other][] ([#17](https://github.com/openscm/pandas-openscm/pull/17))
 
 
 ## Pandas-OpenSCM v0.4.1 (2025-04-12)
@@ -93,21 +93,21 @@ from the examples given in that link.
 
 - Fixed up [pandas_openscm.index_manipulation.update_levels][].
   It now drops unused levels by default first, to avoid applying the updates to values that aren't being used.
-  The same fixes are propagated to [pandas_openscm.accessors.DataFramePandasOpenSCMAccessor.update_index_levels][] and [pandas_openscm.index_manipulation.update_index_levels_func][]. ([#14](https://github.com/openscm/pandas-openscm/pull/14))
+  The same fixes are propagated to [pandas_openscm.accessors.PandasDataFrameOpenSCMAccessor.update_index_levels][] and [pandas_openscm.index_manipulation.update_index_levels_func][]. ([#14](https://github.com/openscm/pandas-openscm/pull/14))
 
 
 ## Pandas-OpenSCM v0.4.0 (2025-04-11)
 
 ### 🆕 Features
 
-- Added [pandas_openscm.index_manipulation.update_levels][] and the corresponding accessor [pandas_openscm.accessors.DataFramePandasOpenSCMAccessor.update_index_levels][] ([#13](https://github.com/openscm/pandas-openscm/pull/13))
+- Added [pandas_openscm.index_manipulation.update_levels][] and the corresponding accessor [pandas_openscm.accessors.PandasDataFrameOpenSCMAccessor.update_index_levels][] ([#13](https://github.com/openscm/pandas-openscm/pull/13))
 
 
 ## Pandas-OpenSCM v0.3.3 (2025-03-30)
 
 ### 🆕 Features
 
-- - Added a method for converting to long data, see [pandas_openscm.accessors.DataFramePandasOpenSCMAccessor.to_long_data][pandas_openscm.accessors.DataFramePandasOpenSCMAccessor.to_long_data] ([#12](https://github.com/openscm/pandas-openscm/pull/12))
+- - Added a method for converting to long data, see [pandas_openscm.accessors.PandasDataFrameOpenSCMAccessor.to_long_data][pandas_openscm.accessors.PandasDataFrameOpenSCMAccessor.to_long_data] ([#12](https://github.com/openscm/pandas-openscm/pull/12))
 
 
 ## Pandas-OpenSCM v0.3.2 (2025-03-27)

docs/further-background/openscmdb-backend-speed/openscmdb-backend-speed-tests.py

@@ -36,7 +36,7 @@
 if GIT_REPO.is_dirty():
     COMMIT = f"{COMMIT}-dirty"
 
-pandas_openscm.register_pandas_accessor()
+pandas_openscm.register_pandas_accessors()
 
 
 @define

docs/how-to-guides/how-to-make-a-plume-plot.py

@@ -29,7 +29,7 @@
 import numpy as np
 import openscm_units
 
-from pandas_openscm import register_pandas_accessor
+from pandas_openscm import register_pandas_accessors
 from pandas_openscm.plotting import PlumePlotter
 from pandas_openscm.testing import create_test_df
 
@@ -40,7 +40,7 @@
 # Register the openscm accessor for pandas objects
 # (we don't do this on import
 # as we have had bad experiences with implicit behaviour like that)
-register_pandas_accessor()
+register_pandas_accessors()
 
 # %% [markdown]
 # ## Basics

docs/pandas-accessors.md

@@ -8,35 +8,43 @@ The accessors must be registered before they can be used
 (we do this to avoid imports of any of our modules having side effects,
 which is a pattern we have had bad experiences with in the past).
 This is done with
-[register_pandas_accessor][pandas_openscm.accessors.register_pandas_accessor],
+[register_pandas_accessors][pandas_openscm.accessors.register_pandas_accessors],
 
 By default, the accessors are provided under the "openscm" namespace
 and this is how the accessors are documented below.
 However, the namespace can be customised when using
-[register_pandas_accessor][pandas_openscm.accessors.register_pandas_accessor],
+[register_pandas_accessors][pandas_openscm.accessors.register_pandas_accessors],
 should you wish to use a different namespace for the accessor.
 
 For the avoidance of doubt, in order to register/activate the accessors,
 you will need to run something like:
 
 ```python
-from pandas_openscm.accessors import register_pandas_accessor
+from pandas_openscm.accessors import register_pandas_accessors
 
-# The 'pd.DataFrame.openscm' namespace will not be available at this point.
+# The 'pd.DataFrame.openscm' and 'pd.Series.openscm' namespace
+# will not be available at this point.
 
 # Register the accessors
-register_pandas_accessor()
+register_pandas_accessors()
 
-# The 'pd.DataFrame.openscm' namespace
+# The 'pd.DataFrame.openscm' and 'pd.Series.openscm' namespace
 # (or whatever other custom namespace you chose to register)
 # will now be available.
 ```
 
 The full accessor API is documented below.
 
-::: pandas_openscm.accessors.DataFramePandasOpenSCMAccessor
+::: pandas_openscm.accessors.dataframe.PandasDataFrameOpenSCMAccessor
     handler: python_accessors
     options:
         namespace: "pd.DataFrame.openscm"
         show_root_full_path: false
         show_root_heading: true
+
+::: pandas_openscm.accessors.series.PandasSeriesOpenSCMAccessor
+    handler: python_accessors
+    options:
+        namespace: "pd.Series.openscm"
+        show_root_full_path: false
+        show_root_heading: true

docs/tutorials/unit-conversion.py

@@ -29,7 +29,7 @@
 import pandas_indexing as pix
 import pint
 
-from pandas_openscm import register_pandas_accessor
+from pandas_openscm import register_pandas_accessors
 from pandas_openscm.testing import create_test_df
 from pandas_openscm.unit_conversion import (
     AmbiguousTargetUnitError,
@@ -45,7 +45,7 @@
 # Register the openscm accessor for pandas objects
 # (we don't do this on import
 # as we have had bad experiences with implicit behaviour like that)
-register_pandas_accessor()
+register_pandas_accessors()
 
 # %% [markdown]
 # ## Basics

src/pandas_openscm/__init__.py

@@ -4,8 +4,8 @@
 
 import importlib.metadata
 
-from pandas_openscm.accessors import register_pandas_accessor
+from pandas_openscm.accessors import register_pandas_accessors
 
 __version__ = importlib.metadata.version("pandas_openscm")
 
-__all__ = ["register_pandas_accessor"]
+__all__ = ["register_pandas_accessors"]