pathpilot 0.2.2__tar.gz → 0.3.1__tar.gz

{pathpilot-0.2.2 → pathpilot-0.3.1}/PKG-INFO

@@ -1,8 +1,7 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.3
 Name: pathpilot
-Version: 0.2.2
+Version: 0.3.1
 Summary: Library that facilitates file and folder manipulation in Python.
-Home-page: https://github.com/zteinck/pathpilot
 License: MIT
 Author: Zachary Einck
 Author-email: zacharyeinck@gmail.com
@@ -14,12 +13,14 @@ Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Requires-Dist: XlsxWriter
 Requires-Dist: cachegrab (>=0.2.2)
-Requires-Dist: clockwork (>=0.2.2)
+Requires-Dist: clockwork (>=0.3.4)
 Requires-Dist: numpy
-Requires-Dist: oddments (>=0.2.0)
+Requires-Dist: oddments (>=0.3.1)
 Requires-Dist: pandas
+Project-URL: Homepage, https://github.com/zteinck/pathpilot
 Project-URL: Repository, https://github.com/zteinck/pathpilot
 Description-Content-Type: text/markdown
 
@@ -42,7 +43,7 @@ pip install pathpilot
 
 
 ## Main Features
-- `File` ➔ Function that assigns new file instances to the correct child class. Many file types are supported natively including: *.xlsx*, *.csv*, *.txt*, *.pickle*, etc. The mapping of file extensions to their respective classes is managed using the `extension_mapping` global dictionary. Unmapped extensions are assigned to the `FileBase` class.
+- `file_factory` ➔ Function that assigns new file instances to the correct child class. Many file types are supported natively including: *.xlsx*, *.csv*, *.txt*, *.pickle*, etc. The mapping of file extensions to their respective classes is managed using the `extension_mapping` global dictionary. Unmapped extensions are assigned to the `FileBase` class.
 - `Folder` ➔ Class for interacting with folders. It is important to be mindful of the `read_only` parameter which, if set to `True`, allows folders to be created or deleted programically.
 
 
@@ -51,7 +52,7 @@ Please note the examples below represent a small fraction of the functionality o
 
 ### Imports
 ```python
-from pathpilot import Folder, File
+from pathpilot import Folder, file_factory
 ```
 
 ### Folders
@@ -79,10 +80,10 @@ new_years_file = january_folder.join('Happy New Year.txt')
 ```
 
 ### Files
-First, we create an instance of the `ExcelFile` class using the `File` function. This occurs automatically by virtue of the `.xlsx` file extension.
+First, we create an instance of the `ExcelFile` class using the `file_factory` function. This occurs automatically by virtue of the `.xlsx` file extension.
 ```python
 # create ExcelFile instance
-file = File(r'C:\Users\MyID\Documents\MyFolder\MyFile.xlsx')
+file = file_factory(r'C:\Users\MyID\Documents\MyFolder\MyFile.xlsx')
 ```
 
 Next, let's check if the file exists. If not, let's save a `pandas` `DataFrame` as an Excel file.
@@ -100,7 +101,7 @@ Creating MyFile.xlsx
 
 Now let's read the file we created as a `DataFrame`.
 ```python
-# read the file we created as a pd.DataFrame 
+# read the file we created as a pd.DataFrame
 df = file.read()
 ```
 

{pathpilot-0.2.2 → pathpilot-0.3.1}/README.md

@@ -17,7 +17,7 @@ pip install pathpilot
 
 
 ## Main Features
-- `File` ➔ Function that assigns new file instances to the correct child class. Many file types are supported natively including: *.xlsx*, *.csv*, *.txt*, *.pickle*, etc. The mapping of file extensions to their respective classes is managed using the `extension_mapping` global dictionary. Unmapped extensions are assigned to the `FileBase` class.
+- `file_factory` ➔ Function that assigns new file instances to the correct child class. Many file types are supported natively including: *.xlsx*, *.csv*, *.txt*, *.pickle*, etc. The mapping of file extensions to their respective classes is managed using the `extension_mapping` global dictionary. Unmapped extensions are assigned to the `FileBase` class.
 - `Folder` ➔ Class for interacting with folders. It is important to be mindful of the `read_only` parameter which, if set to `True`, allows folders to be created or deleted programically.
 
 
@@ -26,7 +26,7 @@ Please note the examples below represent a small fraction of the functionality o
 
 ### Imports
 ```python
-from pathpilot import Folder, File
+from pathpilot import Folder, file_factory
 ```
 
 ### Folders
@@ -54,10 +54,10 @@ new_years_file = january_folder.join('Happy New Year.txt')
 ```
 
 ### Files
-First, we create an instance of the `ExcelFile` class using the `File` function. This occurs automatically by virtue of the `.xlsx` file extension.
+First, we create an instance of the `ExcelFile` class using the `file_factory` function. This occurs automatically by virtue of the `.xlsx` file extension.
 ```python
 # create ExcelFile instance
-file = File(r'C:\Users\MyID\Documents\MyFolder\MyFile.xlsx')
+file = file_factory(r'C:\Users\MyID\Documents\MyFolder\MyFile.xlsx')
 ```
 
 Next, let's check if the file exists. If not, let's save a `pandas` `DataFrame` as an Excel file.
@@ -75,7 +75,7 @@ Creating MyFile.xlsx
 
 Now let's read the file we created as a `DataFrame`.
 ```python
-# read the file we created as a pd.DataFrame 
+# read the file we created as a pd.DataFrame
 df = file.read()
 ```
 

{pathpilot-0.2.2 → pathpilot-0.3.1}/pathpilot/__init__.py

@@ -3,5 +3,5 @@ from .decorators import *
 from .exceptions import *
 from .utils import *
 
-__version__ = '0.2.2'
+__version__ = '0.3.1'
 __author__ = 'Zachary Einck <zacharyeinck@gmail.com>'

{pathpilot-0.2.2 → pathpilot-0.3.1}/pathpilot/_file/_excel.py

@@ -54,8 +54,6 @@ class ExcelFile(FileBase):
         keeps track of the current tab number
     verbose : bool
         if True, information is printed when a worksheet is created or written to.
-    troubleshoot : bool
-        if True, additional information is printed for troubleshooting purposes.
 
     Note:
     --------------------
@@ -73,16 +71,14 @@ class ExcelFile(FileBase):
         f,
         number_tabs=False,
         verbose=True,
-        troubleshoot=False,
         **kwargs
         ):
         super().__init__(f, **kwargs)
         self.format_cache = dict()
         self.sheet_cache = dict()
         self.number_tabs = number_tabs
-        self.page = 0
         self.verbose = verbose
-        self.troubleshoot = troubleshoot
+        self.page = 0
 
 
     #╭-------------------------------------------------------------------------╮
@@ -204,7 +200,8 @@ class ExcelFile(FileBase):
     @property
     def active_sheet(self):
         ''' current active worksheet '''
-        # used __dict__ because hasattr calls __getattr__ when attr not found in __dict__
+        # used __dict__ because hasattr calls __getattr__
+        # when attr not found in __dict__
         if '_active_sheet' not in self.__dict__:
             self.create_worksheet('Sheet1')
         return self._active_sheet
@@ -332,10 +329,6 @@ class ExcelFile(FileBase):
         out : *
             xlsxwriter.worksheet.Worksheet attribute
         '''
-
-        if self.troubleshoot:
-            print(f"self.__getattr__(name='{name}')")
-
         return getattr(self.active_sheet, name)
 
 
@@ -586,10 +579,15 @@ class ExcelFile(FileBase):
 
         if self.verbose:
              size_label = get_size_label(sys.getsizeof(data))
-             print(f"\twriting {size_label} to '{self.active_sheet.name}' tab", end='... ')
+             print(
+                f'\twriting {size_label} to '
+                f'{self.active_sheet.name!r} tab',
+                end='... '
+                )
 
         if not data:
-            if self.verbose: print('SKIPPED')
+            if self.verbose:
+                print('SKIPPED')
             return
 
         start_col, start_row = self.parse_start_cell(start_cell)
@@ -648,10 +646,10 @@ class ExcelFile(FileBase):
         '''
         Description
         ------------
-        Writes a DataFrame to an Excel worksheet. This is an alternative to df.to_excel()
-        that addresses some of its limitations such as not being able format cells that
-        already have a format including the index, headers, and cells that contain dates
-        or datetimes.
+        Writes a DataFrame to an Excel worksheet. This is an alternative to
+        df.to_excel() that addresses some of its limitations such as not being
+        able format cells that already have a format including the index,
+        headers, and cells that contain dates or datetimes.
 
         Parameters
         ------------
@@ -748,10 +746,16 @@ class ExcelFile(FileBase):
         # Check if empty
         if df.empty:
             if raise_on_empty:
-                raise ValueError("'df' argument cannot be empty.")
+                raise ValueError(
+                    "'df' argument cannot be empty."
+                    )
             if len(df.columns) == 0:
-                raise ValueError("'df' argument must have an index or columns")
-            total_row, total_column = False, False
+                raise ValueError(
+                    "'df' argument must have "
+                    "an index or columns."
+                    )
+            total_row = False
+            total_column = False
 
         # Check for duplicate column names
         odd.verify_no_duplicates(df=df, attr='columns')
@@ -761,7 +765,8 @@ class ExcelFile(FileBase):
             total_column_name = 'Total'
             if total_column_name in df.columns:
                 raise ValueError(
-                    f"'df' already has a column named '{total_column_name}'"
+                    "'df' already has a column "
+                    f"named {total_column_name!r}"
                     )
             df[total_column_name] = df.sum(axis=1, numeric_only=True)
 
@@ -776,13 +781,14 @@ class ExcelFile(FileBase):
         numeric_columns -= percent_columns
 
         datelike_columns = set(
-            df.select_dtypes(include=[np.datetime64]).columns.tolist()
+            df.select_dtypes(include=[np.datetime64])\
+            .columns.tolist()
             )
 
         for k in df.columns:
-            if isinstance(k, str) and \
-            odd.column_name_is_datelike(k) and \
-            str(df[k].dtype) != 'timedelta64[ns]':
+            if isinstance(k, str) \
+            and odd.column_name_is_datelike(k) \
+            and not np.issubdtype(df[k].dtype, np.timedelta64):
                 datelike_columns.add(k)
 
         # Parse start cell
@@ -799,6 +805,7 @@ class ExcelFile(FileBase):
 
         # Force data_format to comply with the standard {column name : format}
         if isinstance(data_format, dict):
+            # check if diciontary keys are index/column names
             if not all(k in df.columns for k in data_format):
                 if any(isinstance(v, (list, tuple, dict))
                        for v in data_format.values()):
@@ -807,14 +814,15 @@ class ExcelFile(FileBase):
 
         # Auto-detects the best format for each DataFrame column
         if data_format == 'auto':
-            data_format = dict()
 
             # cascade auto formatting
             if total_row_format is None:
-                total_row_format = 'auto'
+                total_row_format = data_format[:]
 
             if total_column_format is None:
-                total_column_format = 'auto'
+                total_column_format = data_format[:]
+
+            data_format = {}
 
             infer_format = lambda fmt, s: \
                 fmt if s.sum() - s.round().sum() == 0 \
@@ -848,18 +856,33 @@ class ExcelFile(FileBase):
             datetime_columns = set()
 
             for k in list(datelike_columns):
-                if np.issubdtype(df[k].dtype, np.datetime64): continue
+                if np.issubdtype(df[k].dtype, np.datetime64) \
+                    or df[k].isna().all():
+                    continue
+
                 fmt = date_formats.get(k)
+                to_dt = lambda x: pd.to_datetime(x, format=fmt)
+
                 try:
-                    df[k] = pd.to_datetime(df[k], format=fmt)
+                    df[k] = to_dt(df[k])
                 except:
-                    if fmt is None:
-                        datelike_columns.remove(k)
-                    else:
-                        df[k] = df[k].apply(odd.ignore_nan(lambda x: \
-                            datetime.datetime.strptime(x, fmt)
-                            ))
-                        datetime_columns.add(k)
+                    try:
+                        # handles mixed dtypes that will convert individually
+                        df[k] = df[k].apply(odd.ignore_nan(to_dt))
+                    except:
+                        types = set(type(x) for x in df[k].dropna())
+                        if types == {str}:
+                            if fmt is None:
+                                datelike_columns.remove(k)
+                            else:
+                                df[k] = df[k].apply(odd.ignore_nan(lambda x: \
+                                    datetime.datetime.strptime(x, fmt)
+                                    ))
+                                datetime_columns.add(k)
+                        elif all(issubclass(x, datetime.datetime) for x in types):
+                            datetime_columns.add(k)
+                        else:
+                            datelike_columns.remove(k)
 
             for k in datelike_columns:
                 data_format[k] = 'datetime'
@@ -867,7 +890,7 @@ class ExcelFile(FileBase):
                 s = df[k].dropna()
                 if s.empty: continue
                 if k in datetime_columns:
-                    if all(x.time() == datetime.time(0, 0) for x in s.values):
+                    if all(x.time() == datetime.time.min for x in s.values):
                         df[k] = df[k].apply(odd.ignore_nan(lambda x: x.date()))
                         data_format[k] = 'date'
                 else:

{pathpilot-0.2.2 → pathpilot-0.3.1}/pathpilot/_file/base.py

@@ -5,7 +5,6 @@ import os
 import pandas as pd
 import numpy as np
 import oddments as odd
-import clockwork as cw
 from cachegrab import sha256
 
 from .._folder import Folder
@@ -135,34 +134,6 @@ class FileBase(object):
             return wrapper
 
 
-        @staticmethod
-        def add_timestamp(func):
-            '''
-            Parameters
-            ------------
-            args : tuple
-                arguments are only passed to the respective clockwork function
-            kwargs : dict
-                keyword arguments are passed to the respective clockwork function
-                with the exception of 'loc' and 'encase':
-
-                loc : str
-                    the location where you want the timestamp.
-                    Supported values are 'prefix' and 'suffix'
-                encase : bool
-                    if True, the timestamp is encased in paranthesis
-            '''
-
-            def wrapper(self, *args, **kwargs):
-                loc = kwargs.pop('loc', 'prefix')
-                encase = kwargs.pop('encase', False)
-                timestamp = func(self, *args, **kwargs)
-                if encase: timestamp = f'({timestamp})'
-                return getattr(self, loc)(timestamp)
-
-            return wrapper
-
-
         @staticmethod
         def add_affix(func):
             '''
@@ -195,16 +166,16 @@ class FileBase(object):
         '''
         Description
         ------------
-        This method ensures that functions returning new instances create objects
-        of the correct subclass. For instance, if a CSVFile instance is converted
-        to an Excel file, this method guarantees that the returned instance is
-        an ExcelFile object. If subclass typing must be preserved regardless of
-        changes, the subclass can set the factory to None. For example, a
-        CryptoFile should always create instances of CryptoFile even if the
-        file extension is changed.
+        This method ensures that functions returning new instances create
+        objects of the correct subclass. For instance, if a CSVFile instance is
+        converted to an Excel file, this method guarantees that the returned
+        instance is an ExcelFile object. If subclass typing must be preserved
+        regardless of changes, the subclass can set the factory to None. For
+        example, a CryptoFile should always create instances of CryptoFile even
+        if the file extension is changed.
 
-        Note: This must be at the class level since calling self.factory() at
-        the instance level passes self as the first argument.
+        Note: This must be at the class level since calling self.file_factory()
+        at the instance level passes self as the first argument.
 
         Parameters
         ------------
@@ -218,7 +189,8 @@ class FileBase(object):
         file : FileBase subclass instance
             spawned file instance
         '''
-        return (cls if cls.factory is None else cls.factory)(*args, **kwargs)
+        ff = cls.file_factory
+        return (cls if ff is None else ff)(*args, **kwargs)
 
 
     #╭-------------------------------------------------------------------------╮
@@ -489,7 +461,7 @@ class FileBase(object):
 
 
     def deep_copy(self):
-        ''' create a copy of the File object '''
+        ''' create a copy of the file object '''
         return self.spawn(self.path)
 
 
@@ -500,36 +472,4 @@ class FileBase(object):
 
     @Decorators.add_affix
     def suffix():
-        ''' add suffix to file name '''
-
-
-    # helper functions adding timestamps to files
-    @Decorators.add_timestamp
-    def quarter(self, delta=0):
-        return cw.quarter_end(delta=delta).label
-
-
-    def qtr(self, *args, **kwargs):
-        return self.quarter(*args, **kwargs)
-
-
-    @Decorators.add_timestamp
-    def month(self, delta=0):
-        return cw.month_end(delta=delta).ymd
-
-
-    @Decorators.add_timestamp
-    def day(self, weekday, delta=0):
-        return cw.day_of_week(weekday=weekday, delta=delta).ymd
-
-
-    @Decorators.add_timestamp
-    def year(self, delta=0):
-        return str(cw.year_end(delta=delta).year)
-
-
-    @Decorators.add_timestamp
-    def timestamp(self, normalize=False, week_offset=0, fmt=None):
-        now = cw.Date(normalize=normalize, week_offset=week_offset)
-        now = str(now).replace(':','.') if fmt is None else now.str(fmt)
-        return now
+        ''' add suffix to file name '''

{pathpilot-0.2.2 → pathpilot-0.3.1}/pathpilot/_folder/base.py

@@ -3,11 +3,8 @@ import shutil
 import os
 import pandas as pd
 import oddments as odd
-from cachegrab import sha256
-
 import clockwork as cw
-from clockwork.utils import \
-    convert_date_format_to_regex
+from cachegrab import sha256
 
 from ..decorators import check_read_only
 from ..exceptions import ReadOnlyError
@@ -36,7 +33,7 @@ class Folder(object):
 
     Class Attributes
     --------------------
-    factory : object
+    file_factory : object
         Function or class that determines which subclass is returned when
         a new file object is initialized.
     sorter : func
@@ -319,7 +316,7 @@ class Folder(object):
                     raise ValueError(' '.join(message + ['found.']))
 
             if date_format is not None and date_pattern is None:
-                date_pattern = convert_date_format_to_regex(date_format)
+                date_pattern = cw.date_format_to_regex(date_format)
 
             if date_pattern is not None:
                 date_pattern = format_date_pattern(date_pattern)
@@ -454,7 +451,7 @@ class Folder(object):
 
     @classmethod
     def _spawn_file(cls, *args, **kwargs):
-        return cls.factory(*args, **kwargs)
+        return cls.file_factory(*args, **kwargs)
 
 
     @classmethod
@@ -784,7 +781,7 @@ class Folder(object):
 
         Returns
         ----------
-        out : Folder | File
+        out : object
             folder or file object
         '''
         self.validate_join_args(args)
@@ -841,23 +838,6 @@ class Folder(object):
         shutil.copytree(self.path, destination.path)
 
 
-    # helper functions adding timestamps to folders
-    def quarter(self, delta=0, **kwargs):
-        return self.join(cw.quarter_end(delta=delta).label, **kwargs)
-
-
-    def month(self, delta=0, **kwargs):
-        return self.join(cw.month_end(delta=delta).ymd, **kwargs)
-
-
-    def day(self, weekday, delta=0, **kwargs):
-        return self.join(cw.day_of_week(weekday=weekday, delta=delta).ymd, **kwargs)
-
-
-    def year(self, delta=0, **kwargs):
-        return self.join(str(cw.year_end(delta=delta).year), **kwargs)
-
-
     #╭-------------------------------------------------------------------------╮
     #| Static Methods                                                          |
     #╰-------------------------------------------------------------------------╯

{pathpilot-0.2.2 → pathpilot-0.3.1}/pathpilot/core.py

@@ -27,7 +27,7 @@ extension_mapping = {
 #| Functions                                                               |
 #╰-------------------------------------------------------------------------╯
 
-def File(f, **kwargs):
+def file_factory(f, **kwargs):
     ''' assigns new file instances to the correct subclass '''
     extension = trifurcate(f)[-1]
     out = extension_mapping.get(extension, FileBase)(f, **kwargs)
@@ -44,8 +44,8 @@ def get_data_path():
 
 
 #╭-------------------------------------------------------------------------╮
-#| Assign Class Attribute                                                  |
+#| Assign Class Attributes                                                 |
 #╰-------------------------------------------------------------------------╯
 
-FileBase.factory = File
-Folder.factory = File
+FileBase.file_factory = file_factory
+Folder.file_factory = file_factory

{pathpilot-0.2.2 → pathpilot-0.3.1}/pathpilot/utils.py

@@ -1,6 +1,6 @@
 import os
 import datetime
-from clockwork import Date
+import clockwork as cw
 
 
 def split_extension(x):
@@ -53,19 +53,28 @@ def get_cwd():
     return f
 
 
-def _timestamp_to_date(func):
+def _to_timestamp(func):
 
     def wrapper(path):
-        return Date(datetime.datetime.fromtimestamp(func(path)))
+        letter = func.__name__.split('_')[1][0]
+        ts = getattr(os.path, f'get{letter}time')(path)
+
+        # Conversion to datetime is redundant since cw.Timestamp
+        # constructor accepts timestamps, but explicitly using
+        # datetime library ensures time zone information is
+        # respected in case constructor behavior ever changes.
+        dt = datetime.datetime.fromtimestamp(ts)
+
+        return cw.Timestamp(dt)
 
     return wrapper
 
 
-@_timestamp_to_date
-def get_created_date(path):
-    return os.path.getctime(path)
+@_to_timestamp
+def get_created_date():
+    pass
 
 
-@_timestamp_to_date
-def get_modified_date(path):
-    return os.path.getmtime(path)
+@_to_timestamp
+def get_modified_date():
+    pass

{pathpilot-0.2.2 → pathpilot-0.3.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "pathpilot"
-version = "0.2.2"
+version = "0.3.1"
 description = "Library that facilitates file and folder manipulation in Python."
 authors = ["Zachary Einck <zacharyeinck@gmail.com>"]
 license = "MIT"
@@ -10,9 +10,9 @@ homepage = "https://github.com/zteinck/pathpilot"
 
 [tool.poetry.dependencies]
 python = "^3.8"
-clockwork = ">=0.2.2"
+clockwork = ">=0.3.4"
 cachegrab = ">=0.2.2"
-oddments = ">=0.2.0"
+oddments = ">=0.3.1"
 pandas = "*"
 numpy = "*"
 XlsxWriter = "*"