pathpilot 0.3.3__tar.gz → 0.3.4__tar.gz

{pathpilot-0.3.3 → pathpilot-0.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pathpilot
-Version: 0.3.3
+Version: 0.3.4
 Summary: Library that facilitates file and folder manipulation in Python.
 Home-page: https://github.com/zteinck/pathpilot
 License: MIT
@@ -16,9 +16,9 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Requires-Dist: XlsxWriter
 Requires-Dist: cachegrab (>=0.2.2)
-Requires-Dist: clockwork (>=0.3.4)
+Requires-Dist: clockwork (>=0.4.0)
 Requires-Dist: numpy
-Requires-Dist: oddments (>=0.3.1)
+Requires-Dist: oddments (>=0.4.0)
 Requires-Dist: pandas
 Project-URL: Repository, https://github.com/zteinck/pathpilot
 Description-Content-Type: text/markdown

{pathpilot-0.3.3 → pathpilot-0.3.4}/pathpilot/__init__.py

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

{pathpilot-0.3.3 → pathpilot-0.3.4}/pathpilot/_file/_excel.py

@@ -30,22 +30,22 @@ class ExcelFile(FileBase):
     active_sheet : xlsxwriter.worksheet.Worksheet
         The active worksheet
     sheet_cache : dict
-        Dictionary where the keys are worksheet names and values are the worksheet
-        objects. It is important to note that the keys are the original sheet names
-        passed by the user as opposed to the actual name that appears in the excel
-        file and worksheet.name attribute because the latter is truncated by the 31
-        character limit and/or will have a page prefix added per the 'number_tabs'
-        argument. This setup allows the user to access the sheet using the original
-        name.
+        Dictionary where the keys are worksheet names and values are the
+        worksheet objects. It is important to note that the keys are the
+        original sheet names passed by the user as opposed to the actual name
+        that appears in the excel file and worksheet.name attribute because the
+        latter is truncated by the 31 character limit and/or will have a page
+        prefix added per the 'number_tabs' argument. This setup allows the user
+        to access the sheet using the original name.
     formats : dict
-        keys are strings representing names of formats and values are dictionaries
-        containing format parameters. For Example, {{'bold': {'bold': True}}. These
-        are intended to be frequently used formats that can be both used individually
-        and as building blocks for more complex formats (see self.add_format for more
-        information.)
+        Keys are strings representing names of formats and values are
+        dictionaries containing format parameters. For Example, {{'bold':
+        {'bold': True}}. These are intended to be frequently used formats that
+        can be both used individually and as building blocks for more complex
+        formats (see self.add_format for more information.)
     format_cache : dict
-        keys are hashes of sorted dictionaries containing format parameters and
-        values are xlsxwriter.format.Format. This is done so that only one
+        keys are hashes of sorted dictionaries containing format parameters
+        and values are xlsxwriter.format.Format. This is done so that only one
         format instance will be created per unique format used.
     number_tabs : bool
         if True, tabs in the workbook will have a number prefix. For example,
@@ -53,7 +53,8 @@ class ExcelFile(FileBase):
     page : int
         keeps track of the current tab number
     verbose : bool
-        if True, information is printed when a worksheet is created or written to.
+        if True, information is printed when a worksheet is created or written
+        to.
 
     Note:
     --------------------
@@ -299,9 +300,18 @@ class ExcelFile(FileBase):
             'header': {'bold': True,'bottom': True, 'text_wrap': True},
 
             # Conditional
-            'conditional_red': {'bg_color': '#FFC7CE', 'font_color': '#9C0006'},
-            'conditional_green': {'bg_color': '#C6EFCE', 'font_color': '#006100'},
-            'conditional_yellow': {'bg_color': '#FFEB9C', 'font_color': '#9C6500'},
+            'conditional_red': {
+                'bg_color': '#FFC7CE',
+                'font_color': '#9C0006'
+                },
+            'conditional_green': {
+                'bg_color': '#C6EFCE',
+                'font_color': '#006100'
+                },
+            'conditional_yellow': {
+                'bg_color': '#FFEB9C',
+                'font_color': '#9C6500'
+                },
             }
 
         return format_presets
@@ -316,8 +326,8 @@ class ExcelFile(FileBase):
         Description
         ------------
         Called when an attribute is referenced that does not exist. In this
-        case, attributes that do not exist will be assumed to be active worksheet
-        object attributes (e.g. '.hide_gridlines').
+        case, attributes that do not exist will be assumed to be active
+        worksheet object attributes (e.g. '.hide_gridlines').
 
         Parameters
         ------------
@@ -387,11 +397,12 @@ class ExcelFile(FileBase):
         Parameters
         ------------
         args : pd.DataFrame | list | dict
-            • if list, each dataframe in the list is written to a separate worksheet.
-            • if dict, the keys are considered sheet names and the values should be
-                       dataframes. (i.e. {'My Sheet 1': df1, 'My Sheet 2': df2}).
-                       You may not pass a sheets argument when passing a dictionary
-                       as the args argument.
+            • if list, each dataframe in the list is written to a separate
+                worksheet.
+            • if dict, the keys are considered sheet names and the values
+                should be DataFrames. (i.e. {'My Sheet 1': df1, 'My Sheet 2':
+                df2}). You may not pass a sheets argument when passing a
+                dictionary as the args argument.
         sheets : list | str | None
             Mist of sheet names. Must be None when 'args' is a dictionary.
         kwargs : dict
@@ -407,15 +418,16 @@ class ExcelFile(FileBase):
             if isinstance(args, dict):
                 if sheets is not None:
                     raise ValueError(
-                        "'sheets' argument must be None when a dictionary is passed"
+                        "'sheets' argument must be None "
+                        "when a dictionary is passed"
                         )
                 sheets = list(args.keys())
                 args = list(args.values())
             else:
-                args = odd.to_iter(args)
+                args = odd.ensure_list(args)
 
             if sheets is not None:
-                sheets = odd.to_iter(sheets)
+                sheets = odd.ensure_list(sheets)
                 if len(args) != len(sheets):
                     raise ValueError(
                         f"length of 'args' ({len(args)}) != length of 'sheets' "
@@ -482,44 +494,44 @@ class ExcelFile(FileBase):
         ------------
         start_cell : str | tuple
             Individual cell range to be used as the starting position for the
-            fill. May be a standard excel range (e.g. 'A2') or a tuple of length
-            two (column, row) (e.g. (1, 2) | ('A', 2)).
+            fill. May be a standard excel range (e.g. 'A2') or a tuple of
+            length two (column, row) (e.g. (1, 2) | ('A', 2)).
         data : 1D list | 2D list | single value | pd.DataFrame | pd.Series
-            Data to be written to excel worksheet starting in start_cell.
-            Each sub-list is treated as row data and written in sequential order.
-            For example, if start_cell = 'A1' and data = [[1, 2, 3], ['a', 'b', 'c']],
-            then row 1 and 2 will be filled with 1, 2, 3 and 'a', 'b', 'c', respectively.
-        formatting : str | dict | one-dimensional list | one-dimensional tuple | None
+            Data to be written to excel worksheet starting in start_cell. Each
+            sub-list is treated as row data and written in sequential order.
+            For example, if start_cell = 'A1' and data = [[1, 2, 3], ['a', 'b',
+            'c']], then row 1 and 2 will be filled with 1, 2, 3 and 'a', 'b',
+            'c', respectively.
+        formatting : str | dict | list(1D) | tuple(1D) | None
             Excel formatting to be applied to data. Supported types include:
-                • str ➜ Strings are interpreted as self.formats dictionary keys.
-                         Passing a single string (e.g. formatting='bold') causes
-                         the corresponding format to be be universally applied to
-                         all data cells.
+                • str ➜ Strings are interpreted as self.formats dictionary
+                    keys. Passing a single string (e.g. formatting='bold')
+                    causes the corresponding format to be be universally
+                    applied to all data cells.
                 • dict ➜ Dictionaries are interpreted as format parameters.
-                          Passing a single dictionary (e.g. formatting =
-                          {'bold': True, 'num_format': '#,##0'}) causes the
-                          corresponding format to be be universally applied
-                          to all data cells.
+                    Passing a single dictionary (e.g. formatting = {'bold':
+                    True, 'num_format': '#,##0'}) causes the corresponding
+                    format to be be universally applied to all data cells.
                 • list | tuple ➜ formats included in a list/tuuple are applied
-                                  to columns in sequential order. If the length
-                                  of the list/tuple is shorter than the number
-                                  of columns then no format is applied to the
-                                  remaining columns.
+                    to columns in sequential order. If the length of the list
+                    or tuple is shorter than the number of columns then no
+                    format is applied to the remaining columns.
                 • None ➜ no formatting is applied.
         inverse : bool
-            If True, the 2D data is inverted such that each sub-list is treated
-            as column data as opposed to row data under the default behavior.
-            (e.g. [[1, 2, 3], ['a', 'b', 'c']] ➜ [[1, 'a'], [2, 'b'], [3, 'c']]
+            If True, the 2D data is inverted such that each sub-list is
+            treated as column data as opposed to row data under the default
+            behavior. For example:
+            [[1, 2, 3], ['a', 'b', 'c']] ➜ [[1, 'a'], [2, 'b'], [3, 'c']]
         repeat : int
             If 'data' argument is a single data element then it will be repeated
             or duplicated this number of times.
         sheet : str
-            If None, self.active_sheet is utilized. If self.active_sheet has not
-                     yet been assigned, it will be assigned to a newly created
-                     blank worksheet named 'Sheet1'.
-            If not None, self.active_sheet will be assigned to the passed sheet name.
-                         If the passed name does not correspond to an existing sheet,
-                         it will be created.
+            If None, self.active_sheet is utilized. If self.active_sheet has
+                not yet been assigned, it will be assigned to a newly created
+                blank worksheet named 'Sheet1'.
+            If not None, self.active_sheet will be assigned to the passed
+                sheet name. If the passed name does not correspond to an
+                existing sheet, it will be created.
         outer_border : bool
             If True, data is encased in an outer border.
 
@@ -666,60 +678,60 @@ class ExcelFile(FileBase):
         data_format : ↑
             Special cases:
             • 'auto' ➜ formatting is automatically applied to numeric, percent,
-                        and date fields.
+                and date fields.
             • dict ➜ if the dictionary keys are only comprised of 'df' index or
-                      column names then the values are treated like format
-                      parameters and formatting is only applied to those columns
-                      included in the keys. If not all the key values are column
-                      names then the dictionary receives the default treatment
-                      outlined in the self.write documentation. (e.g.
-                      {'Price': 'commas', 'Total': {'bold': True}})
+                column names then the values are treated like format parameters
+                and formatting is only applied to those columns included in the
+                keys. If not all the key values are column names then the
+                dictionary receives the default treatment outlined in the
+                self.write documentation. (e.g.{'Price': 'commas', 'Total':
+                {'bold': True}})
             Other cases:
                 see self.write 'formatting' argument documentation.
         column_widths : 'auto' | list | tuple | dict
-            • 'auto' ➜ xlsxwriter does not support auto-fitting column widths so
-                           this attempts replicate it by setting the column width
-                           according to the length of the values in each column
-                           (up to a certain limit).
+            • 'auto' ➜ xlsxwriter does not support auto-fitting column widths
+                so this attempts replicate it by setting the column width
+                according to the length of the values in each column (up to a
+                certain limit).
             • list | tuple ➜ widths are applied to columns in sequential order.
-                           If the length of the list/tuple is shorter than the
-                           number of columns then the width is not set on the
-                           remaining columns.
+                If the length of the list/tuple is shorter than the
+                number of columns then the width is not set on the
+                remaining columns.
             • dict ➜ dictionary where keys are DataFrame column names and values
-                           are column widths. Any column names excluded from the
-                           dictionary will not have their widths set.
+                are column widths. Any column names excluded from the dictionary
+                will not have their widths set.
         date_format : None | str | dict
             Defines how date-like columns are parsed when data_format='auto'
             (e.g. '%Y-%m-%d'). Options include:
             • None ➜ format is inferred.
             • str ➜ used for all date-like columns.
             • dict ➜ dictionary where keys are DataFrame column names and values
-                      are formats. Any column names excluded from the dictionary
-                      default to None.
+                are formats. Any column names excluded from the dictionary
+                default to None.
         normalize : bool
             if True, any date columns where the hours, minutes, seconds,
-                     microseconds are all set to zero (midnight) will be converted
-                     from a datetime to date.
+                microseconds are all set to zero (midnight) will be converted
+                from a datetime to date.
         autofilter : bool
             if True, a filter will be applied to the column headers.
         raise_on_empty : bool
             if True and the 'df' argument is empty, an exception will be raised.
             if False, the 'df' columns will be written to an otherwise empty
-                      worksheet.
+                worksheet.
         total_row : bool
-            if True, a row is added at the bottom reflecting the sum of each numeric
-                     column.
+            if True, a row is added at the bottom reflecting the sum of each
+                numeric column.
         total_row_format : ^
-            format applied if 'total_row' is True. If None and data_format='auto',
-            then the same formatting will be applied to the total row plus bold
-            and a top border.
+            format applied if 'total_row' is True. If None and data_format =
+            'auto', then the same formatting will be applied to the total row
+            plus bold and a top border.
         total_column : bool
-            if True, a column is added at the end reflecting the sum of all numeric
-            values in each row.
+            if True, a column is added at the end reflecting the sum of all
+            numeric values in each row.
         total_column_format : ^
-            format applied if 'total_column' is True. If None and data_format='auto',
-            then the same formatting will be applied to the total column plus bold and
-            a left border.
+            format applied if 'total_column' is True. If None and data_format =
+            'auto', then the same formatting will be applied to the total column
+            plus bold and a left border.
 
         Returns
         ------------
@@ -730,7 +742,7 @@ class ExcelFile(FileBase):
 
         odd.validate_value(
             value=date_format,
-            attr='date_format',
+            name='date_format',
             types=(str, dict),
             none_ok=True
             )
@@ -740,7 +752,7 @@ class ExcelFile(FileBase):
             raise NotImplementedError
 
         # Reset index
-        if odd.get_index_names(df):
+        if odd.has_named_index(df):
             df.reset_index(inplace=True)
 
         # Check if empty
@@ -758,7 +770,7 @@ class ExcelFile(FileBase):
             total_column = False
 
         # Check for duplicate column names
-        odd.verify_no_duplicates(df=df, attr='columns')
+        odd.verify_unique(df, column_names=True)
 
         # Add a total column to dataframe
         if total_column:
@@ -880,11 +892,14 @@ class ExcelFile(FileBase):
                             if fmt is None:
                                 datelike_columns.remove(k)
                             else:
-                                df[k] = df[k].apply(odd.ignore_nan(lambda x: \
-                                    datetime.datetime.strptime(x, fmt)
+                                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):
+                        elif all(
+                            issubclass(x, datetime.datetime)
+                            for x in types
+                            ):
                             datetime_columns.add(k)
                         else:
                             datelike_columns.remove(k)
@@ -936,7 +951,7 @@ class ExcelFile(FileBase):
 
             if total_column_format == 'auto':
                 data_format[total_column_name] = \
-                    self.add_format(odd.to_iter(
+                    self.add_format(odd.ensure_list(
                         data_format.pop(total_column_name, [])
                         ) + ['bold','left'])
             else:
@@ -964,8 +979,12 @@ class ExcelFile(FileBase):
             last_row = first_row + len(df) - 1
             for k in df.columns:
                 if k in numeric_columns:
-                    col = self.get_column_letter(start_col + df.columns.get_loc(k))
-                    total_row.append(f'=SUM({col}{first_row}:{col}{last_row})')
+                    col = self.get_column_letter(
+                        start_col + df.columns.get_loc(k)
+                        )
+                    total_row.append(
+                        f'=SUM({col}{first_row}:{col}{last_row})'
+                        )
                 else:
                     total_row.append(None)
 
@@ -973,8 +992,10 @@ class ExcelFile(FileBase):
                 total_row_format = []
                 for k in df.columns:
                     fmt = ['bold','top']
-                    if total_column and k == total_column_name: fmt.append('left')
-                    if k in data_format: fmt.append(data_format[k])
+                    if total_column and k == total_column_name:
+                        fmt.append('left')
+                    if k in data_format:
+                        fmt.append(data_format[k])
                     total_row_format.append(fmt)
 
             if total_row_format is None and data_format is not None:
@@ -1044,20 +1065,22 @@ class ExcelFile(FileBase):
         Parameters
         ------------
         start_cell : str | tuple | list
-            Individual cell range to be used as the starting position for the fill.
-            May be a standard excel range (e.g. 'A2') or a tuple of length two
-            (column, row) (e.g. (1, 2) | ('A', 2)). Similar to the formula argument,
-            column names may include placeholders (e.g. '{Price}2' | ('{Price}', 2)).
+            Individual cell range to be used as the starting position for the
+            fill. May be a standard excel range (e.g. 'A2') or a tuple of
+            length two (column, row) (e.g. (1, 2) | ('A', 2)). Similar to the
+            formula argument, column names may include placeholders (e.g.
+            '{Price}2' | ('{Price}', 2)).
         formula : str
-            Excel formula to be written to the start cell and used as a fill template.
-            Column names may include placeholders with header names if 'headers'
-            argument is passed (e.g. '=A1+B1-{Price}1'. Placeholders make the formula
-            robust to changes in header positioning.
+            Excel formula to be written to the start cell and used as a fill
+            template. Column names may include placeholders with header names
+            if 'headers' argument is passed (e.g. '=A1+B1-{Price}1'.
+            Placeholders make the formula robust to changes in header
+            positioning.
         limit : int
             Number of rows or columns to fill.
         headers : list
-            List of column header names. Required argument when placeholders are
-            used in formula or start_cell.
+            List of column header names. Required argument when placeholders
+            are used in formula or start_cell.
         formatting : str
             see write() argument of the same name.
         down : bool
@@ -1086,7 +1109,8 @@ class ExcelFile(FileBase):
 
         components = list(set(re.findall('([a-zA-Z]+)(\d+)', formula)))
         cols, rows = zip(*components)
-        cols, rows = [self.get_column_index(x) + 1 for x in cols], [int(x) for x in rows]
+        cols = [self.get_column_index(x) + 1 for x in cols]
+        rows = [int(x) for x in rows]
 
         build_counter = lambda x: \
             OrderedDict((i, k) for i, k in enumerate(sorted(list(set(x)))))
@@ -1104,7 +1128,10 @@ class ExcelFile(FileBase):
         for x in range(limit):
             format_args = list(counter.values())
             if not down:
-                format_args = [self.get_column_letter(c - 1) for c in format_args]
+                format_args = [
+                    self.get_column_letter(c - 1)
+                    for c in format_args
+                    ]
             data.append(formula.format(*format_args))
             for k in counter:
                 counter[k] += 1
@@ -1130,19 +1157,17 @@ class ExcelFile(FileBase):
         ------------
         name : str | tuple | list
             • str ➜ name of new format.
-                     If 'fmt' is None, if the name is already in self.formats
-                        then no action is taken. If the name does not already
-                        exist then the name's components (delimited by underscores
-                        ('_')) will be combined into a new format (e.g.
-                        'bold_commas').
-                     if 'fmt' is not None, if the name conflicts with an existing
-                        format name, the existing format will be overwritten.
-            • tuple | list ➜ If 'fmt' is None, components will be combined into a
-                              new format. For example, self.add_format(
-                              name=['bold','commas'], fmt=None) would add the
-                              following entry to self.formats: {'bold_commas':
-                              {'bold': True, 'num_format': '#,##0'}
-
+                If 'fmt' is None, if the name is already in self.formats then
+                    no action is taken. If the name does not already exist then
+                    the name's components (delimited by underscores ('_')) will
+                    be combined into a new format (e.g.'bold_commas').
+                if 'fmt' is not None, if the name conflicts with an existing
+                    format name, the existing format will be overwritten.
+            • tuple | list ➜ If 'fmt' is None, components will be combined
+                into a new format. For example, self.add_format(name=
+                ['bold','commas'], fmt=None) would add the following entry to
+                self.formats: {'bold_commas': {'bold': True, 'num_format':
+                '#,##0'}
         fmt : dict | None
             • dict ➜ see https://xlsxwriter.readthedocs.io/format.html
             • None ➜ format will be constructed based on the components
@@ -1150,23 +1175,29 @@ class ExcelFile(FileBase):
         Returns
         ------------
         out : str
-            name of format (in other words, the self.formats dictionary key value)
+            Name of format (in other words, the self.formats dictionary key
+            value)
         '''
         if fmt is None:
             if isinstance(name, str):
-                if name in self.formats: return name
+                if name in self.formats:
+                    return name
                 name = name.split('_')
-            if not isinstance(name, (tuple, list)):
-                raise TypeError(
-                    f"'name' arguments of type {type(name).__name__} not supported."
-                    )
+
+            odd.validate_value(
+                value=name,
+                name=name,
+                types=(tuple, list)
+                )
+
             fmt = dict()
             for k in name: fmt.update(self.formats[k])
             name = '_'.join(odd.natural_sort(name))
         else:
             if not isinstance(name, str):
                 raise TypeError(
-                    "'name' argument must be a string if 'fmt' is not None, not: "
+                    "'name' argument must be a string "
+                    "if 'fmt' is not None, not: "
                     f"{type(fmt).__name__}"
                     )
 

{pathpilot-0.3.3 → pathpilot-0.3.4}/pathpilot/_file/_sqlite.py

@@ -35,8 +35,8 @@ class SQLiteFile(FileBase):
     def update_query(tbl_name, update_cols, where_cols, where_logic=''):
         sql = 'UPDATE {0} SET {1} WHERE {2} {3}'.format(
             tbl_name,
-            ', '.join('[%s] = ?' % x for x in odd.to_iter(update_cols)),
-            ' AND '.join('[%s] = ?' % x for x in odd.to_iter(where_cols)),
+            ', '.join('[%s] = ?' % x for x in odd.ensure_list(update_cols)),
+            ' AND '.join('[%s] = ?' % x for x in odd.ensure_list(where_cols)),
             where_logic
             )
         return sql
@@ -46,8 +46,8 @@ class SQLiteFile(FileBase):
     def select_query(tbl_name, select_cols, where_cols, where_logic=''):
         sql = 'SELECT {1} FROM {0} WHERE {2} {3}'.format(
             tbl_name,
-            ', '.join('[%s]' % x for x in odd.to_iter(select_cols)),
-            ' AND '.join('[%s] = ?' % x for x in odd.to_iter(where_cols)),
+            ', '.join('[%s]' % x for x in odd.ensure_list(select_cols)),
+            ' AND '.join('[%s] = ?' % x for x in odd.ensure_list(where_cols)),
             where_logic
             )
         return sql
@@ -57,7 +57,7 @@ class SQLiteFile(FileBase):
     def delete_query(tbl_name, where_cols, where_logic=''):
         sql = 'DELETE FROM {0} WHERE {1} {2}'.format(
             tbl_name,
-            ' AND '.join('[%s] = ?' % x for x in odd.to_iter(where_cols)),
+            ' AND '.join('[%s] = ?' % x for x in odd.ensure_list(where_cols)),
             where_logic
             )
         return sql
@@ -151,8 +151,11 @@ class SQLiteFile(FileBase):
     def format_payload(self, tbl_name, col_names, payload):
         if isinstance(payload, tuple): payload = [payload]
         mapping = self.data_types(tbl_name)
-        payload = [tuple([mapping[col](cell) if pd.notnull(cell) else None
-                          for col,cell in zip(col_names, row)]) for row in payload]
+        payload = [
+            tuple([mapping[col](cell) if pd.notnull(cell) else None
+            for col, cell in zip(col_names, row)])
+            for row in payload
+            ]
         return payload
 
 
@@ -187,7 +190,7 @@ class SQLiteFile(FileBase):
             df.reset_index(inplace=True)
 
         df.rename(columns={x: x.lower() for x in df.columns}, inplace=True)
-        col_names = [x for x in odd.lower_iter(self.columns(tbl_name))
+        col_names = [x for x in odd.lower_iterable(self.columns(tbl_name))
                      if x in set(list(df.columns))]
         df = df[col_names]
 
@@ -197,9 +200,14 @@ class SQLiteFile(FileBase):
                 )
 
         if where_cols:
-            where_cols = odd.lower_iter(odd.to_iter(where_cols))
+            where_cols = odd.lower_iterable(odd.ensure_list(where_cols))
             col_names = [x for x in col_names if x not in where_cols]
-            sql = self.update_query(tbl_name, col_names, where_cols, where_logic)
+            sql = self.update_query(
+                tbl_name,
+                col_names,
+                where_cols,
+                where_logic
+                )
             col_names.extend(where_cols)
             df = df[col_names]
         else:
@@ -216,12 +224,17 @@ class SQLiteFile(FileBase):
     def copy_as_temp(self, target_name, temp_name=None, index=None):
         ''' creates temporary table based on permanent table '''
         temp_name = temp_name or target_name
-        sql = f'CREATE TEMP TABLE {temp_name} AS SELECT * FROM {target_name} LIMIT 0;'
+
+        sql = f'CREATE TEMP TABLE {temp_name} AS ' + \
+              f'SELECT * FROM {target_name} LIMIT 0;'
+
         self.c.execute(sql)
         self.conn.commit()
 
         if index:
-            sql = f"CREATE INDEX temp.idx ON {temp_name}({', '.join(odd.to_iter(index))})"
+            sql = f"CREATE INDEX temp.idx ON {temp_name}(%s)" % \
+                ', '.join(odd.ensure_list(index))
+
             self.c.execute(sql)
             self.conn.commit()
 

{pathpilot-0.3.3 → pathpilot-0.3.4}/pathpilot/_file/_zip.py

@@ -48,24 +48,27 @@ class ZipFile(FileBase):
         Parameters
         ------------
         payload : str | list | tuple | FileBase | Folder
-            str representing a single file or folder or list or tuple comprised
-            of str, FileBase, or Folder representing files and folders to be
-            zipped
+            String representing a single file or folder or a list or tuple
+            comprised of string, FileBase, or Folder objects representing
+            files and folders to be zipped.
         delete_original : bool
             If True, zipped files/folders are deleted after being zipped
         filter_func : callable
-            function applied to every file in the folder (argument will be of
-            type FileBase). If filter_func returns True for a given file it will
-            be included in the zip process otherwise excluded (e.g. filters out
-            files that are not of file extention .py lambda x: x.ext == 'py').
+            Function applied to every file in the folder (argument will be of
+            type FileBase). If filter_func returns True for a given file it
+            will be included in the zip process otherwise excluded (e.g.
+            filters out files that are not of file extention .py lambda x:
+            x.ext == 'py').
         include_folders : bool
-            if True, each object being zipped will be placed in a folder
-            mirroring the name of the folder in which the unzipped version resides.
-            This argument cannot be true when files_only is True.
+            If True, each object being zipped will be placed in a folder
+            mirroring the name of the folder in which the unzipped version
+            resides.
+            Note: This argument cannot be true when files_only is True.
         files_only : bool
-            if True, zip folder will only include individual files, folders are
-            disregarded. For example, if you pass a folder that contains subfolders,
-            all the individual files will be zipped and subfolders are discarded.
+            if True, zip folder will only include individual files, folders
+            are disregarded. For example, if you pass a folder that contains
+            subfolders, all the individual files will be zipped and subfolders
+            are discarded.
             This is the default behavior when 'payload' contains files. This
             argument cannot be True when include_folder is True.
         verbose : bool
@@ -83,14 +86,19 @@ class ZipFile(FileBase):
             'C:/Folder C/'
             ]
 
-        'Folder C' contains 'File 3.txt' and a subfolder 'Folder D' with a file called
-        'File 4.txt'.
+        'Folder C' contains 'File 3.txt' and a subfolder 'Folder D' with a
+        file called 'File 4.txt'.
 
         • Default (include_folders=False, files_only=False)
-            Under default behavior the only time a folder will be included in the zip
-            folder is when a passed folder contains subfolders
+            Under default behavior the only time a folder will be included in
+            the zip folder is when a passed folder contains subfolders
 
-            Output: ['File 1.txt', 'File 2.txt', 'File 3.txt', 'Folder D/File 4.txt']
+            Output: [
+                'File 1.txt',
+                'File 2.txt',
+                'File 3.txt',
+                'Folder D/File 4.txt'
+                ]
 
         • include_folders=True
             Every file will retain the folder in which it resides
@@ -155,7 +163,8 @@ class ZipFile(FileBase):
 
         if include_folders and files_only:
             raise ValueError(
-                "'include_folders' and 'files_only' arguments cannot both be True"
+                "'include_folders' and 'files_only' "
+                "arguments cannot both be True."
                 )
 
         if not isinstance(payload, (list, tuple)):
@@ -174,8 +183,14 @@ class ZipFile(FileBase):
                 folder_can_be_deleted = True
 
                 for f in obj.walk():
-                    zipped = zip_file(f, f.directory[:-1].replace(obj.parent.path, '').split('/'))
-                    if not zipped: folder_can_be_deleted = False
+                    p = f.directory[:-1]\
+                        .replace(obj.parent.path, '')\
+                        .split('/')
+
+                    zipped = zip_file(f, p)
+
+                    if not zipped:
+                        folder_can_be_deleted = False
 
                 if delete_original and folder_can_be_deleted:
                     shutil.rmtree(obj.path)

{pathpilot-0.3.3 → pathpilot-0.3.4}/pathpilot/_file/base.py

@@ -383,7 +383,9 @@ class FileBase(object):
     def trifurcate_and_fill(self, f):
         ''' trifurcates file and fills gaps with instance attributes '''
         folder, name, ext = trifurcate(f, default_folder=False)
-        f = (folder or self.directory) + (name or self.name) + '.' + (ext or self.ext)
+        f = (folder or self.directory) + \
+            (name or self.name) + '.' + \
+            (ext or self.ext)
         return self.spawn(f)
 
 
@@ -447,8 +449,8 @@ class FileBase(object):
 
 
     def swap(self, **kwargs):
-        ''' quick way of intitializing a new file with different attribute(s)
-            (e.g. you have a csv file and want an xlsx file of the same name) '''
+        ''' returns a new file instance with different attribute(s) (e.g.
+            you have a csv file and want an xlsx file of the same name) '''
         alias_map = {'folder': 'directory', 'ext': 'extension'}
         kwargs = {alias_map.get(k, k): v for k, v in kwargs.items()}
         directory, name, extension = [

{pathpilot-0.3.3 → pathpilot-0.3.4}/pathpilot/_folder/backup.py

@@ -32,8 +32,8 @@ def backup_folder(
     shallow : bool
         filecmp.cmp(f1, f2, shallow=True) shallow argument.
         "If shallow is true and the os.stat() signatures (file type, size, and
-        modification time) of both files are identical, the files are taken to be
-        equal."
+        modification time) of both files are identical, the files are taken to
+        be equal."
         https://docs.python.org/3/library/filecmp.html
     verbose : bool
         if True, all folders and files that were backed up or overwritten are

{pathpilot-0.3.3 → pathpilot-0.3.4}/pathpilot/_folder/base.py

@@ -87,13 +87,15 @@ class Folder(object):
         '''
         Description
         --------------------
-        Class that enables operations on all contents of a folder collectively,
-        including obtaining metadata, filtering, deleting, and more. This class
-        encompasses both files and folders but you can access them separetly by
-        using the Files and Folders subclasses, respectively.
+        Class that enables operations on all contents of a folder
+        collectively, including obtaining metadata, filtering, deleting,
+        and more. This class encompasses both files and folders but you can
+        access them separetly by using the Files and Folders subclasses,
+        respectively.
 
-        Note: This class and its subclasses are intended to be accessed indirectly
-        by using the 'contents', 'folders', and 'files' Folder cached properties.
+        Note: This class and its subclasses are intended to be accessed
+        indirectly by using the 'contents', 'folders', and 'files' Folder
+        cached properties.
 
         Class Attributes
         --------------------
@@ -205,7 +207,8 @@ class Folder(object):
                 Example:
                 ------------
                 Consider a folder that contains multiple files that include a
-                YYYY-MM-DD timestamp in the name such as '2024-06-23 Budget.xlsx'.
+                YYYY-MM-DD timestamp in the name such as
+                '2024-06-23 Budget.xlsx'.
                 In this case you might pass date_pattern=r'\d{4}\-\d{2}\-\d{2}'
 
             date_format : str
@@ -214,35 +217,37 @@ class Folder(object):
                     • 'date_pattern' is None ➜ an attempt will be made to derive
                       the regex pattern using 'date_format' as the template.
                     • 'date_pattern' is not None ➜ 'date_format' is optional but
-                      it can be included if you do not want to rely on pd.to_datetime
-                      inferring the format.
+                      it can be included if you do not want to rely on
+                      pd.to_datetime inferring the format.
 
                 Example:
                 ------------
                 Dealing with the same example from above, all the following
                 combinations will achieve the same result since the None values
                 being inferred:
-                    • date_pattern=r'\d{4}\-\d{2}\-\d{2}', date_format='%Y-%m-%d'
+                    • date_pattern=r'\d{4}\-\d{2}\-\d{2}',
+                      date_format='%Y-%m-%d'
                     • date_pattern=None, date_format='%Y-%m-%d'
                     • date_pattern=r'\d{4}\-\d{2}\-\d{2}', date_format=None
 
             ext : str
                 If not None, only those file objects with this file extension
                 will be considered candidates. This argument may be passed with
-                or without a period and is not case sensitive (e.g. '.txt', 'txt',
-                '.TXT' are all valid).
+                or without a period and is not case sensitive (e.g. '.txt',
+                'txt', '.TXT' are all valid).
             index : int
-                If not None, the object at this integer index in the filtered and
-                sorted data is returned.
+                If not None, the object at this integer index in the filtered
+                and sorted data is returned.
             sort_by : str
-                Name of self.meta_data column to sort by. This argument must be None
-                if the 'date_pattern' or 'date_format' arguments are not None. Defaults
-                to the object created date if None.
+                Name of self.meta_data column to sort by. This argument must
+                be None if the 'date_pattern' or 'date_format' arguments are
+                not None. Defaults to the object created date if None.
             ascending : bool
-                If True, data is sorted in ascending order, otherwise, descending order.
-                If the 'date_pattern' or 'date_format' arguments are not None, the sort
-                will occur on the timestamps extracted from the object names, otherwise,
-                the column denoted by the 'sort_by' argument is used.
+                If True, data is sorted in ascending order, otherwise,
+                descending order. If the 'date_pattern' or 'date_format'
+                arguments are not None, the sort will occur on the timestamps
+                extracted from the object names, otherwise, the column denoted
+                by the 'sort_by' argument is used.
             errors : bool
                 determines how exceptions are handled:
                     • 'raise': exception is raised
@@ -278,8 +283,9 @@ class Folder(object):
             else:
                 if date_format or date_pattern:
                     raise ValueError(
-                        "cannot pass 'sort_by' argument if either 'date_format' "
-                        "or 'date_pattern' arguments are not None."
+                        "cannot pass 'sort_by' argument if either "
+                        "'date_format' or 'date_pattern' arguments are "
+                        "not None."
                         )
 
             kind = self.__class__.__name__.lower()
@@ -311,12 +317,15 @@ class Folder(object):
 
                 if df.empty:
                     if errors == 'ignore': return
-                    message = [f"no {kind} matching name pattern '{name_pattern}'"]
-                    if ext is not None: message.append(f"with extension '.{ext}'")
+                    message = [
+                        f"no {kind} matching name pattern '{name_pattern}'"
+                        ]
+                    if ext is not None:
+                        message.append(f"with extension '.{ext}'")
                     raise ValueError(' '.join(message + ['found.']))
 
             if date_format is not None and date_pattern is None:
-                date_pattern = cw.date_format_to_regex(date_format)
+                date_pattern = cw.temporal_format_to_regex(date_format)
 
             if date_pattern is not None:
                 date_pattern = format_date_pattern(date_pattern)
@@ -333,15 +342,18 @@ class Folder(object):
                         )
 
                 s = pd.to_datetime(s.dropna(), format=date_format)
-                df = df.join(s, how='inner').sort_values(by=s.name, ascending=ascending)
+
+                df = df.join(s, how='inner')\
+                    .sort_values(by=s.name, ascending=ascending)
 
             if index is not None:
-                if not isinstance(index, int):
-                    raise TypeError(
-                        f"'index' argument must be an integer, not {type(index)}"
-                        )
+                odd.validate_value(
+                    value=index,
+                    name='index',
+                    types=int
+                    )
                 try:
-                    return self.to_dict()[ df.iloc[index].name ]
+                    return self.to_dict()[df.iloc[index].name]
                 except Exception as error:
                     if errors == 'ignore': return
                     raise error
@@ -682,7 +694,8 @@ class Folder(object):
                 self._subfolder_cache[key] = folder
                 return self._subfolder_cache[key]
 
-        # cache subfolder that does not exist yet (it will now if read_only=False)
+        # cache subfolder that does not exist yet
+        # (it will now if read_only=False)
         if self.troubleshoot:
             print(f"could not find subfolder = '{name}'")
 
@@ -746,16 +759,17 @@ class Folder(object):
 
                 >> C:/Users/Me/MyFolder/A/B/
 
-            • Strings preceded by a period prior to the final argument are treated
-              like dot folders:
+            • Strings preceded by a period prior to the final argument are
+              treated like dot folders:
 
                 folder.join('.A','.B','C')
 
                 >> C:/Users/Me/MyFolder/.A/.B/C/
 
-            • Strings preceded by a period that are also the final argument present
-              a special case. It will be treated as a dot file unless you add a slash
-              slash to signal you intend for it to be considered a dot folder.
+            • Strings preceded by a period that are also the final argument
+              present a special case. It will be treated as a dot file unless
+              you add a slash to signal you intend for it to be considered a
+              dot folder.
 
                 In this case, .env would be a dot folder subfile in folder B.
 
@@ -790,7 +804,8 @@ class Folder(object):
 
         if is_file(f):
             if not self.read_only:
-                # creates the folder(s) in the file path if they do not already exist
+                # creates the folder(s) in the file path if they do not
+                # already exist
                 self.join(*f.replace(self.path,'').split('/')[:-1])
             return self.spawn_file(f, **kwargs)
 
@@ -847,7 +862,11 @@ class Folder(object):
         ''' verify join args are valid '''
 
         error_template = 'Invalid join argument detected at index %d:'
-        period_rules = 'However, arguments may begin with or contain a single period.'
+
+        period_rules = (
+            'However, arguments may begin with '
+            'or contain a single period.'
+            )
 
         for index, arg in enumerate(args):
             err_msg = error_template % index

pathpilot-0.3.4/pathpilot/exceptions.py

@@ -0,0 +1,7 @@
+
+
+class ReadOnlyError(Exception):
+
+    def __init__(self, message=None):
+        default = 'cannot perform this action in read-only mode'
+        super().__init__(message or default)

{pathpilot-0.3.3 → pathpilot-0.3.4}/pathpilot/utils.py

@@ -41,7 +41,8 @@ def trifurcate(f, default_folder=True):
     f = f + '/' if explicitly_folder or '.' not in f.split('/')[-1] else f
     if f.split('/')[0][-4:].lower() == '.com': f = '//' + f
     f = f.rsplit('/', 1)
-    folder = f[0] + '/' if len(f) == 2 else (get_cwd() if default_folder else '')
+    folder = f[0] + '/' if len(f) == 2 else \
+        (get_cwd() if default_folder else '')
     name, ext = split_extension(f[-1])
     return folder, name, ext.lower()
 

{pathpilot-0.3.3 → pathpilot-0.3.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "pathpilot"
-version = "0.3.3"
+version = "0.3.4"
 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.3.4"
+clockwork = ">=0.4.0"
 cachegrab = ">=0.2.2"
-oddments = ">=0.3.1"
+oddments = ">=0.4.0"
 pandas = "*"
 numpy = "*"
 XlsxWriter = "*"

pathpilot-0.3.3/pathpilot/exceptions.py

@@ -1,6 +0,0 @@
-
-
-class ReadOnlyError(Exception):
-
-    def __init__(self, message=None):
-        super().__init__(message or 'cannot perform this action in read-only mode')