Merge pull request #7 from cityofkamloops/parameters-variables

connection object for filepass

README.md

@@ -0,0 +1,149 @@
+# Filepass Package #
+
+Filepass package is a comprehensive Python package designed to facilitate the transfer of the files across different locations and protocols with ease.
+It supports SFTP, SMB, and LOCAL file systems, and offers functionalities like file renaming (in single file mode) and selective file transfer based on assigned filter.
+It also offeres advanced file management features such as conditional deletion of files.
+With support for both custom handler and local logging, 'Filepass' ensures that you can keep a detailed log of your file trasnfers, making troubleshooting and monitoring a breeze.
+
+
+## Features ##
+
+- **Multiple Protocols Support**:
+Seamlessly transfer files using SFTP, SMB, and LOCAL file systems.
+
+- **Flexible File Selection**:
+Use 'from_filter' parameter to specify exactly which files to transfer, supporting both specific filenames and wildcards for multiple files.
+
+- **File Renaming (in single file transfer mode)**
+Easily rename files during single file transfer mode.
+
+- **Connection Objects**:
+Utilize the pre-defined connnection objects for efficient and secure connections to server.
+
+- **Conditional File Deletion**:
+Automatically delete older files at the destination before transfer using 'to_delete', or remove source files after a successful transfer using 'from_delete'.
+
+- **Advanced Logging**:
+Enable custom logging handler by defining the server name, port number and adding the handler to the logger defined. Otherwise, default to local logging to stdout for monitoring and troubleshooting.
+
+## Installation ##
+
+pip install filepass
+
+## Quick Start ##
+1. Import Filepass package:
+    e.g.:
+    ```from filepass import file_pass, ConnectionDetails, FilepassMethod```
+
+2. Set up connection - create a connection object (ConnectionDetails) based on your protocol of choice. FilepassMethod offers three protocols: SFTP, SMB, and LOCAL
+    e.g.:
+
+        ```python
+        sourceServer = ConnectionDetails(
+        method=FilepassMethod.SMB,
+        user="user",
+        password="password",
+        server="servername",
+        port="portnumber",
+        dir="directory/folder",
+        share="SMB share",
+        )
+        destinationServer = ConnectionDetails(
+            method=FilepassMethod.SFTP,
+            user="user",
+            password="password",
+            server="servername",
+            port="portnumber",
+            dir="directory/folder",
+        )
+        ```
+
+
+3. Configure Logging:
+    (Optional)
+    If you want to enable custom handler logging, such as Graylog logging. Set the server details as follows:
+    Example: Graylog
+        * Import the required library for custom logging - import graypy
+        * Add the handler to your defined logger:
+
+            ```python
+            handler = graypy. graypy.GELFTCPHandler(
+                ("servername"), int("portnumber")
+            )
+            ```
+
+    If you want to simply use local logging:
+        * Import python logging package.
+        * Define the logger and handler.
+            * E.g., handler = logging.StreamHandler(sys.stdout)
+        * Add the handler to your defined logger.
+
+4. Define the required parameters for file transfer:
+    * from_filter = "filename/wildcard"
+        * e.g.
+            ```python
+            from_filter = "*.txt"  #transfers all files in the directory, with .txt extension.
+            from_filter = "transfer_file.csv"  #transfers the selected file.```
+    * to_delete = "yes or no".
+    * from_delete = "yes or no".
+    * logger = set custom handler or local handler.
+
+5. Rename file in single file transfer mode:
+    Rename a file during transfer by specifying the new_filename parameter such as:
+    * e.g.,
+    ```python
+    new_filename = "newfilename"
+    ```
+
+    Defaults to 'None', if parameter is not defined.
+
+6. Transfer Files:
+    Use the file_pass method to move files to move files from one location to another.
+    * e.g.,
+        ```python
+        file_pass(
+            logger,
+            from_conn,
+            to_conn,
+            from_filter,
+            to_delete,
+            from_delete,
+            new_filename,
+        )
+        ```
+
+## Support ##
+If you encounter any issues or have questions, please file an issue on our [GitHub Issues Page](https://github.com/cityofkamloops/filepass/issues)
+
+
+## Contributing ##
+Contributions to Filepass are welcome! Please refer to our [Contribution Guidelines](https://docs.github.com/en/contributing)
+### Ways to Contribute ###
+    * Submit bug reports and feature requests.
+    * Write and improve documentation.
+    * Write code for new features and bug fixes.
+    * Review pull requests.
+    * Enhance the package's test coverage.
+
+### Code of Conduct ###
+    - Participation in this project is governed by The City of Kamloops Code of Conduct. We expect everyone to uphold the principles of respect, kindness and cooperation.
+
+### How to submit contributions ###
+* Reporting bugs:
+    - Use the issue tracker to report bugs.
+    - Describe the bug and include steps to reproduce.
+
+* Feature Requests:
+    - Submit feature requests using the issue tracker.
+    - Please include an explanation why the feature would be useful, and how it should work if possible.
+
+* Pull Requests:
+    - Fork the repository and create your branch from 'main'.
+    - If you have added code, please include tests.
+    - Ensure your project lints and follows the project's coding conventions.
+    - Write a clear and descriptive commit message.
+    - Open a pull request with a clear title and description.
+
+## Thank you!! ##
+
+### Happy file transferring! ###

cli.py

@@ -4,35 +4,37 @@
 
 import graypy
 
-from src.filepass import file_pass
+from src.filepass import ConnectionDetails, FilepassMethod, file_pass
 
 
 def main():
     # Load Environmental Variables
 
-    # GREYLOG_SERVER
-    # GREYLOG_PORT
-    # INTEGRATION_NAME
+    # Connection objects
+    from_conn = ConnectionDetails(
+        method=FilepassMethod.SFTP,
+        user=os.environ.get("FROMUSER"),
+        password=os.environ.get("FROMPW"),
+        server=os.environ.get("FROMSVR"),
+        port=os.environ.get("FROMPORT"),
+        dir=os.environ.get("FROMDIR"),
+        share=os.environ.get("FROMSMBSHARE"),
+    )
+
+    to_conn = ConnectionDetails(
+        method=FilepassMethod.SMB,
+        user=os.environ.get("TOUSER"),
+        password=os.environ.get("TOPW"),
+        server=os.environ.get("TOSVR"),
+        port=os.environ.get("TOPORT"),
+        dir=os.environ.get("TODIR"),
+        share=os.environ.get("TOSMBSHARE"),
+    )
 
-    from_user = os.environ.get("FROMUSER")
-    from_pw = os.environ.get("FROMPW")
-    from_svr = os.environ.get("FROMSVR")
-    from_port = os.environ.get("FROMPORT")
-    from_dir = os.environ.get("FROMDIR")
-    from_share = os.environ.get("FROMSMBSHARE")
-    from_method = os.environ.get("FROMMETHOD")
+    # Parameters required by file_pass
     from_delete = os.environ.get("FROMDELETE")
     from_filter = os.environ.get("FROMFILEFILTER")
-
-    to_user = os.environ.get("TOUSER")
-    to_pw = os.environ.get("TOPW")
-    to_svr = os.environ.get("TOSVR")
-    to_port = os.environ.get("TOPORT")
-    to_dir = os.environ.get("TODIR")
-    to_share = os.environ.get("TOSMBSHARE")
-    to_method = os.environ.get("TOMETHOD")
     to_delete = os.environ.get("TODELETE")
-    # Environment variable added for filename change in single file mode
     new_filename = os.environ.get("NEW_FILENAME")
 
     filepass_logger = logging.getLogger("filepass_logger")
@@ -51,19 +53,11 @@ def main():
     logger = logging.LoggerAdapter(
         filepass_logger,
         {
-            "from_method": from_method,
-            "from_user": from_user,
-            "from_svr": from_svr,
-            "from_port": from_port,
-            "from_share": from_share,
-            "from_dir": from_dir,
+            "from_conn": from_conn,
+            "from_delete": from_delete,
             "from_filter": from_filter,
-            "to_method": to_method,
-            "to_user": to_user,
-            "to_svr": to_svr,
-            "to_port": to_port,
-            "to_share": to_share,
-            "to_dir": to_dir,
+            "to_conn": to_conn,
+            "to_delete": to_delete,
             "integration": "filepass",
             "filepass_name": os.environ.get("INTEGRATION_NAME"),
             "new_filename": new_filename,
@@ -72,22 +66,10 @@ def main():
     try:
         file_pass(
             logger,
-            from_user,
-            from_pw,
-            from_svr,
-            from_port,
-            from_dir,
-            from_share,
-            from_method,
+            from_conn,
             from_delete,
             from_filter,
-            to_user,
-            to_pw,
-            to_svr,
-            to_port,
-            to_dir,
-            to_share,
-            to_method,
+            to_conn,
             to_delete,
             new_filename,
         )

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "filepass"
-version = "0.4.0"
+version = "0.5.0"
 authors = [
     { name="Orlund Norstrom", email="[email protected]" },
     { name="Marco Lussetti", email="[email protected]" },

src/filepass/__init__.py

@@ -1,7 +1,11 @@
-from .filepass import (
-    file_pass,
-    local_connection,
-    osfs_connection,
-    sftp_connection,
-    smb_connection,
-)
+from .filepass import file_pass, osfs_connection, sftp_connection, smb_connection
+from .filepass_config import ConnectionDetails, FilepassMethod
+
+__all__ = [
+    "ConnectionDetails",
+    "FilepassMethod",
+    "sftp_connection",
+    "smb_connection",
+    "osfs_connection",
+    "file_pass",
+]