Move path import, update docs (#7)

* Move path import and fix empty string bug

* Add quickstart

* Add history, update version

HISTORY.md

@@ -0,0 +1,8 @@
+# History
+
+## v0.3.0 (2021-03-14)
+
+- Added HISTORY.md file
+- Changed import syntax to `from pandas_path import path` to better support custom accessors. This means that we do not register `.path` unless you import `.path` so that in other libraries you don't have to add the `.path` accessor if you are just registering your own custom accessor.
+- Added quickstart section to README
+- Fix bug where we tried to instantiate with blank string for an example rather than first item in the Series

README.md

@@ -10,6 +10,42 @@ This package is for you. Just one import adds a `.path` accessor to any pandas S
 
 <small> * If not, you should.</small>
 
+## Quickstart
+
+Install latest `pandas-path` with `pip`.
+
+```bash
+pip install pandas-path
+```
+
+Import `path` from `pandas_path`, and then the `.path` accessor will be available on any Series or Index:
+
+```python
+# this is all you need
+from pandas_path import path
+```
+
+Now you can use all the pathlib methods using the `.path` accessor on any Series in `pandas`!
+
+```python
+pd.Series([
+    'cat/1.jpg',
+    'cat/2.jpg',
+    'dog/1.jpg',
+    'dog/2.jpg',
+]).path.parent
+
+# 0    cat
+# 1    cat
+# 2    dog
+# 3    dog
+# dtype: object
+```
+
+
+## Examples
+
+
 Here's an example:
 
 ```python
@@ -18,7 +54,7 @@ import pandas as pd
 
 # This is the only line you need to register `.path` as an accessor
 # on any Series or Index in pandas.
-import pandas_path
+from pandas_path import path
 
 # we'll make an example series from the py files in this repo;
 # note that every element here is just a string--no need to make Path objects yourself

pandas_path/accessor.py

@@ -1,4 +1,3 @@
-from pathlib import Path
 from types import FunctionType, LambdaType, MethodType
 
 import numpy as np
@@ -42,11 +41,12 @@ def __getattr__(self, attr):
 
             apply_series = self._obj.to_series() if isinstance(self._obj, pd.Index) else self._obj
 
-            # check the type of this attribute on a Path object
+            # check the type of this attribute on a Path object (we need an actual instance) since
+            # the super classes dispatch
             if isinstance(self._obj.values[0], path_class):
                 attr_type = getattr(type(self._obj.values[0]), attr, None)
             else:
-                attr_type = getattr(type(self._to_path_object("")), attr, None)
+                attr_type = getattr(type(self._to_path_object(self._obj.values[0])), attr, None)
 
             # if we're asking for a property, do the calculation and return the result
             if isinstance(attr_type, property):
@@ -137,7 +137,3 @@ def register_path_accessor(accessor_name, path_class, *args, **kwargs):
 
     pd.api.extensions.register_series_accessor(accessor_name)(accessor_class)
     pd.api.extensions.register_index_accessor(accessor_name)(accessor_class)
-
-
-# default to registering `Path` to `path`
-register_path_accessor("path", Path)

pandas_path/path/__init__.py

@@ -0,0 +1,6 @@
+from pathlib import Path
+
+from ..accessor import register_path_accessor  # noqa
+
+
+register_path_accessor("path", Path)

pandas_path/tests.py

@@ -24,6 +24,7 @@ def pd():
 @pytest.fixture
 def pandas_path():
     import pandas_path
+    from pandas_path import path  # noqa
 
     assert pandas_path.__version__ is not None
 

setup.py

@@ -31,7 +31,7 @@ def load_reqs(path):
         "Source Code": "https://github.com/drivendataorg/pandas-path",
         "DrivenData": "http://drivendata.co",
     },
-    version="0.2.0",
+    version="0.3.0",
     author="DrivenData",
     author_email="[email protected]",
     include_package_data=True,