Metadata-Version: 2.1
Name: cheesefactory-sftp
Version: 0.35
Summary: A (soon to be) beautiful SFTP wrapper for Paramiko.
Home-page: https://bitbucket.org/hellsgrannies/cheesefactory-sftp
Author: Todd Salazar
Author-email: unixsal@yahoo.com
License: UNKNOWN
Description: # cheesefactory-sftp
        
        -----------------
        
        #### A beautiful SFTP wrapper for Paramiko.
        [![PyPI Latest Release](https://img.shields.io/pypi/v/cheesefactory-sftp.svg)](https://pypi.org/project/cheesefactory-sftp/)
        [![PyPI status](https://img.shields.io/pypi/status/cheesefactory-sftp.svg)](https://pypi.python.org/pypi/cheesefactory-sftp/)
        [![PyPI download month](https://img.shields.io/pypi/dm/cheesefactory-sftp.svg)](https://pypi.python.org/pypi/cheesefactory-sftp/)
        [![PyPI download week](https://img.shields.io/pypi/dw/cheesefactory-sftp.svg)](https://pypi.python.org/pypi/cheesefactory-sftp/)
        [![PyPI download day](https://img.shields.io/pypi/dd/cheesefactory-sftp.svg)](https://pypi.python.org/pypi/cheesefactory-sftp/)
        
        ### Note
        
        This is a major rewrite, now based on Paramiko. The focus has been on basic GET and PUT. As such, some features are not yet finished and this README is woefully inadequate, but things will soon be better than ever.
        
        If I did something bad for you in with this update, I'm sorry. Please `import cheesefactory-sftp==0.33`
        
        ### Main Features
        
        **Note:** _This package is still in beta status. As such, future versions may not be backwards compatible and features may change. Parts of it may even be broken._
        
        * Built using paramiko.
        
        ### Coming Soon
        
        TBA
        
        ### Connect to the remote SFTP server
        
        -----------------
        ```python
        from cheesefactory-sftp import CfSftp
        
        sftp = CfSftp.connect(
            host='mysftp.example.com',
            port='22',
            username='testuser',
            password='testpass',
        )
        ```
        
        Argument | Type | Default | Description
        :--- | :--- | :--- | :---
        **host** | str | `127.0.0.1` | Remote server. 
        **port** | str | `'22'` | SFTP TCP port. 
        **user** | str | | SFTP username
        **password** | str | |  SFTP password
        **key_path** | str | | Path to private key file.
        **key_password** | | str | Password for encrypted private key.
        
        
        
        ### Get or Put a file
        
        ```python
        transfer_log = sftp.get(
            remote_path='/remote_dir/remote_file.txt',
            local_path='/local_dir/local_file.txt', 
            preserve_mtime=False,
            remove_source=False
        )
        
        ...
        
        transfer_log = sftp.put(
            remote_path='/remote_dir/remote_file.txt',
            local_path='/local_dir/local_file.txt', 
            preserve_mtime=False,
            remove_source=False
        )
        ```
        
        Argument | Type  | Default | Description
        :--- |:------|:--------| :---
        **local_path** | str   |         | Local/destination path and filename.
        **log_checksum** | bool  | `False` | Calculate file SHA256 checksum and log resulting value.
        **preserve_mtime** | boole | `False` | Keep modification time of source file.
        **remote_path** | str   |         |  Remote/source path and filename.
        **remove_source** | bool  | `False`  | Remove the remote source file.
        
        
        
        ### Get or Put multiple files
        
        ```python
        transfer_log = sftp.get_by_list(
            log_checksum=False,
            preserve_mtime=True, 
            file_list=[
                {'src:': '/remote_dir_a/file1.txt', 'dst': '/local_dir/file_a.txt'},
                {'src:': '/remote_dir_a/file2.txt', 'dst': '/local_dir/file_b.txt'},
                {'src:': '/remote_dir_b/file1.txt', 'dst': '/local_dir/file_c.txt'},
            ],
            remove_source=False
        )
        
        ...
        
        transfer_log = sftp.put_by_list(
            log_checksum=False,
            preserve_mtime=True, 
            file_list=[
                {'src:': '/remote_dir_a/file1.txt', 'dst': '/local_dir/file_a.txt'},
                {'src:': '/remote_dir_a/file2.txt', 'dst': '/local_dir/file_b.txt'},
                {'src:': '/remote_dir_b/file1.txt', 'dst': '/local_dir/file_c.txt'},
            ],
            remove_source=False
        )
        ```
        
        Argument | Type       | Default | Description
        :--- |:-----------|:--------| :---
        **log_checksum** | bool       | `False` | Calculate file SHA256 checksum and log resulting value.
        **preserve_mtime** | bool       | `True`  | Keep modification time of source file.
        **file_list** | List[dict] |         | List of dictionaries in the format [{'src': '<source path>', 'dst': '<destination path>'}, ...]
        **remove_source** | bool       | `False` | Remove the remote source file.
        
        
        
        
        # Other methods
        
        #### close()
        
        Close the SFTP connection.
        
        ```python
        sftp = CfSftp.connect(...)
        sftp.close()
        ```
        
        #### status()
        
        Retrieve connection status.
        
        ```python
        sftp = SFTP.connect(...)
        status, message = sftp.status()
        ```
        
        Returns:
        1. True (connected) or False (not connected), and
        2. 'Transport open and authenticated', 'Transport open. Not authenticated', or 'Transport closed, Not authenticated'
        
        ### File and Directory Methods
        
        Method | Description
        :--- | :---
        [chdir()](#chdir) | Change current remote directory.
        [chmod()](#chmod) | Change the permissions of a remote file.
        [chown()](#chown) | Change the owner and group of a remote file.
        [cwd()](#cwd) | Return the current remote directory.
        [delete()](#remove_file) | Alias for remove_file(). **DEPRECATED**
        [exists()](#exists) | Does a remote file or directory exist?
        [file_size_match()](#file_size_match) | Determine if the sizes of a remote and a local file match.
        [is_dir()](#is_dir) | Is the current remote path a directory?
        [is_file()](#is_file) | Is the current remote path a file?
        [list_dir()](#list_dir) | Return a list of remote directory contents (without `.` and `..`).
        [list_files()](#list_dir) | Return a list of remote directory contents (without `.` and `..`). **DEPRECATED**
        [mkdir()](#mkdir) | Create a remote directory.
        [remove()](#remove) | Delete a remote file or directory.
        [remove_dir()](#remove_dir) | Delete a remote directory.
        [remove_file()](#remove_file) | Delete a remote file.
        [rename()](#rename) | Rename a remote flie or folder.
        [stat()](#stat) | Retrieve information about a remote file. Mimics Python's os.stat structure.
        
        ---
        
        #### chdir()
        
        Change current remote directory.
        
        ```python
        sftp = SFTP.connect(...)
        sftp.chdir('/tmp/downloads')
        ```
        
        Args:</br>
        &emsp;_path_ (`str`): New remote directory.
        
        ---
        
        #### chmod()
        
        Change the permissions of a remote file.
        
        ```python
        sftp = SFTP.connect(...)
        sftp.chmod(path='/tmp/myfile', mode=644)
        ```
        
        Args:</br>
        &emsp;_path_ (`str`): Remote file path.</br>
        &emsp;_mode_ (`int`): Unix-style permission (e.g. 0644)
        
        ---
        
        #### chown()
        
        Change the owner and group of a remote file.
        
        ```python
        sftp = SFTP.connect(...)
        sftp.chown(path='/tmp/myfile', uid=1003, gid=1003)
        ```
        
        Args:</br>
        &emsp;_path_ (`str`): Remote file path.</br>
        &emsp;_uid_ (`int`): New user ID.</br>
        &emsp;_gid_ (`int`): New group ID.
        
        ---
        
        #### cwd()
        
        Return the current remote directory.
        
        ```python
        sftp = SFTP.connect(...)
        sftp.cwd()
        ```
        
        Returns:</br>
        &emsp;(`str`) Current remote working directory.
        
        ---
        
        #### exists()
        
        Does a remote file or directory exist?
        
        ```python
        sftp = SFTP.connect(...)
        sftp.exists('/tmp/myfile')
        ```
        
        Args:</br>
        &emsp;_path_ (`str`): File or directory to test.</br>
        
        Returns:</br>
        &emsp;(`int`) **True** if file or directory exists. **False** if it does not.
        
        ---
        
        #### is_dir()
        
        Is the current remote path a directory?
        
        ```python
        sftp = SFTP.connect(...)
        sftp.is_dir()
        ```
        
        Args:</br>
        &emsp;_path_ (`str`): The path to test.
        
        Returns:</br>
        &emsp;(`bool`) **True** if it is, **False** if it ain't.
        
        ---
        
        #### is_file()
        
        Is the current remote path a file?
        
        ```python
        sftp = SFTP.connect(...)
        sftp.is_file()
        ```
        
        Args:</br>
        &emsp;_path_ (`str`): The path to test.
        
        Returns:</br>
        &emsp;(`bool`) **True** if it is, **False** if it is not.
        
        ---
        
        #### list_dir()
        
        Return a list of remote directory contents (without `.` and `..`).
        
        ```python
        sftp = SFTP.connect(...)
        sftp.list_dir()
        ```
        
        Args:</br>
        &emsp;_path_ (`str`): Remote path.</br>
        &emsp;_recursive_ (`bool`): Include contents of sub-directories in output?
        
        Returns:</br>
        &emsp;(`list`) A list of directory contents.
        
        ---
        
        #### mkdir()
        
        Create a remote directory.
        
        ```python
        sftp = SFTP.connect(...)
        sftp.mkdir()
        ```
        
        Args:</br>
        &emsp;_path_ (`str`): Name of the folder to create.</br>
        &emsp;_mode_ (`int`): Posix-style permissions for the folder. Given in octal (without preceding 0)
        
        ---
        
        #### remove()
        
        Delete a remote file or directory.
        
        ```python
        sftp = SFTP.connect(...)
        sftp.remove()
        ```
        
        Args:</br>
        &emsp;_path_ (`str`): Relative or absolute path of file or directory to delete.
        
        Raises:</br>
        &emsp;`IOError`: if path is neither directory nor file.
        
        ---
        
        #### remove_dir()
        
        Delete a remote directory.
        
        ```python
        sftp = SFTP.connect(...)
        sftp.remove_dir()
        ```
        
        Args:</br>
        &emsp;_path_ (`str`): Relative or absolute path of directory to delete.
        
        ---
        
        #### remove_file()
        
        Delete a remote file.
        
        ```python
        sftp = SFTP.connect(...)
        sftp.remove_file()
        ```
        
        Args:</br>
        &emsp;_path_ (`str`): Relative or absolute path of file to delete.
        
        ---
        
        #### rename()
        
        Rename a remote flie or folder.
        
        ```python
        sftp = SFTP.connect(...)
        sftp.rename()
        ```
        
        Args:</br>
        &emsp;_old_path_ (`str`): Existing name of file or directory.
        &emsp;_new_path_ (`str`): New name for the file or directory. Must not already exist.
        
        ---
        
        #### stat()
        
        Retrieve information about a remote file. Mimics Python's os.stat structure. 
        
        Supported fields: st_mode, st_size, st_uid, st_gid, st_atime, and st_mtime. 
        
        ```python
        sftp = SFTP.connect(...)
        sftp.stat()
        ```
        
        Args:</br>
        &emsp;_path_ (`str`): The filename to stat.
        
        Returns:</br>
        &emsp;(`paramiko.SFTPAttributes()`) Attributes about the given file.
        
        
        ## Log
        
        Metrics concerning the status and performance of CfSftp are available via the `log` attribute.
        
        ```python
        sftp = CfSftp.connect(
            host='mysftp.example.com',
            port='22',
            username='testuser',
            password='testpass',
        )
        ```
        ```python
        >>> sftp.log
        {'sftp_host': 'mysftp.example.com', 'sftp_password': 'testpass', 'sftp_port': '22', 'sftp_username': 'testuser'}
        ```
        
        ### Log keys
        
        The following log keys are available:
        
          * connection_ok: bool (Was the SFTP connection established successfully?)
          * connection_note: str (Connection problem details)
          * host: str
          * last_utility_note
          * password: str
          * port: str
          * transfers: List (Details for each transfer during the SFTP session.)
            * action: 'GET' or 'PUT'
            * action_ok: bool
            * client: str
            * local_path: str
            * note: str
            * preserve_mtime: bool
            * preserve_mtime_ok: bool
            * remote_path: str
            * remove_source: bool
            * remove_source_ok: bool
            * size: int
            * size_match: bool
            * size_match_ok: bool
            * status: 'OK', 'ERROR'
          * user: str
        
        
Keywords: cheesefactory sftp development
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Description-Content-Type: text/markdown
