pathpilot 0.1.0__tar.gz

pathpilot-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Zachary Einck
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pathpilot-0.1.0/PKG-INFO

@@ -0,0 +1,94 @@
+Metadata-Version: 2.1
+Name: pathpilot
+Version: 0.1.0
+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
+Requires-Python: >=3.8,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: clockwork
+Requires-Dist: iterlab
+Requires-Dist: numpy
+Requires-Dist: pandas
+Project-URL: Repository, https://github.com/zteinck/pathpilot
+Description-Content-Type: text/markdown
+
+# pathpilot
+`pathpilot` is a library that facilitates file and folder manipulation in Python. It was designed with an emphasis on `pandas` compatibility to ensure smooth workflows.
+
+### Core Utilities
+`pathpilot` has two core utilities:
+- `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.
+- `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.
+
+## Example Usage
+Please note the examples below represent a small fraction of the functionality offered by `pathpilot`. Please refer to the documentation within the code for more information.
+
+### Imports
+```python
+from pathpilot import Folder, File
+```
+
+### Folders
+First, we create an instance of the `Folder` class. Passing `read_only=False` causes the folder to be created if it does not already exist.
+```python
+# initiate a folder instance
+folder = Folder(r'C:\Users\MyID\Documents\MyFolder', read_only=False)
+```
+
+Moreover, any subfolders that are referenced while interacting with the folder instance will also be created automatically. Let's use the `join` method to create a couple subfolders.
+```python
+# create subfolders (i.e. C:\Users\MyID\Documents\MyFolder\Year\2025\Month\)
+month_folder = folder.join('Year', '2025', 'Month')
+```
+
+Alternatively, you can access subfolders by referencing attributes that may or may not already exist.
+```python
+# create a new subfolder called "January" by accessing it via attribute
+january_folder = month_folder.january
+```
+
+Joining to a file will return a file object instead.
+```python
+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.
+```python
+# create ExcelFile instance
+file = File(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.
+```python
+# export a pd.DataFrame to the file, if it does not already exist
+if not file.exists:
+  df = pd.DataFrame({'id': [1, 2, 3], 'data': ['a', 'b', 'c']})
+  file.save(df)
+```
+<pre>
+Creating MyFile.xlsx
+        writing 72.00 B to 'Sheet1' tab... DONE
+        writing 80.00 B to 'Sheet1' tab... DONE
+</pre>
+
+Now let's read the file we created as a `DataFrame`.
+```python
+# read the file we created as a pd.DataFrame 
+df = file.read()
+```
+
+On second thought, let's delete the file.
+```python
+# delete the file we created
+file.delete()
+```

pathpilot-0.1.0/README.md

@@ -0,0 +1,71 @@
+# pathpilot
+`pathpilot` is a library that facilitates file and folder manipulation in Python. It was designed with an emphasis on `pandas` compatibility to ensure smooth workflows.
+
+### Core Utilities
+`pathpilot` has two core utilities:
+- `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.
+- `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.
+
+## Example Usage
+Please note the examples below represent a small fraction of the functionality offered by `pathpilot`. Please refer to the documentation within the code for more information.
+
+### Imports
+```python
+from pathpilot import Folder, File
+```
+
+### Folders
+First, we create an instance of the `Folder` class. Passing `read_only=False` causes the folder to be created if it does not already exist.
+```python
+# initiate a folder instance
+folder = Folder(r'C:\Users\MyID\Documents\MyFolder', read_only=False)
+```
+
+Moreover, any subfolders that are referenced while interacting with the folder instance will also be created automatically. Let's use the `join` method to create a couple subfolders.
+```python
+# create subfolders (i.e. C:\Users\MyID\Documents\MyFolder\Year\2025\Month\)
+month_folder = folder.join('Year', '2025', 'Month')
+```
+
+Alternatively, you can access subfolders by referencing attributes that may or may not already exist.
+```python
+# create a new subfolder called "January" by accessing it via attribute
+january_folder = month_folder.january
+```
+
+Joining to a file will return a file object instead.
+```python
+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.
+```python
+# create ExcelFile instance
+file = File(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.
+```python
+# export a pd.DataFrame to the file, if it does not already exist
+if not file.exists:
+  df = pd.DataFrame({'id': [1, 2, 3], 'data': ['a', 'b', 'c']})
+  file.save(df)
+```
+<pre>
+Creating MyFile.xlsx
+        writing 72.00 B to 'Sheet1' tab... DONE
+        writing 80.00 B to 'Sheet1' tab... DONE
+</pre>
+
+Now let's read the file we created as a `DataFrame`.
+```python
+# read the file we created as a pd.DataFrame 
+df = file.read()
+```
+
+On second thought, let's delete the file.
+```python
+# delete the file we created
+file.delete()
+```

pathpilot-0.1.0/pathpilot/__init__.py

@@ -0,0 +1,4 @@
+from .pathpilot import *
+
+__version__ = '0.1.0'
+__author__ = 'Zachary Einck <zacharyeinck@gmail.com>'