Merge pull request #51 from byteskeptical/bbl_drop-py

Bump & Build

Author: byteskeptical

.github/workflows/document.yml

@@ -16,7 +16,7 @@ jobs:
       fail-fast: true
       matrix:
         os: [ubuntu-latest]
-        python-version: ['3.11']
+        python-version: ['3.12']
 
     steps:
       - name: Clone Repository
@@ -27,7 +27,7 @@ jobs:
           python-version: ${{ matrix.python-version }}
       - name: Build
         run: |
-          python -m pip install paramiko Sphinx sphinx_rtd_theme
+          python -m pip install -e .[doc]
           mkdir _static
           make clean
           make html

.github/workflows/publish.yml

@@ -14,7 +14,7 @@ jobs:
       fail-fast: true
       matrix:
         os: [ubuntu-latest]
-        python-version: ['3.11']
+        python-version: ['3.12']
 
     steps:
       - name: Clone Repository
@@ -30,7 +30,7 @@ jobs:
           python -m pip install --upgrade pip
           pip install build paramiko
       - name: Build
-        run: python -m build --sdist --wheel .
+        run: python -m build --sdist --verbose --wheel .
       - name: Publish to Test PyPI
         if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags')
         uses: pypa/gh-action-pypi-publish@release/v1

.github/workflows/test.yml

@@ -12,8 +12,11 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        os: [ubuntu-latest, macos-latest, windows-latest]
-        python-version: ['3.7', '3.8', '3.9', '3.10', '3.11']
+        os: [ubuntu-latest, macos-13, macos-latest, windows-latest]
+        python-version: ['3.7', '3.8', '3.9', '3.10', '3.11', '3.12']
+        exclude:
+          - os: macos-latest
+            python-version: 3.7
 
     steps:
       - name: Clone Repository
@@ -54,7 +57,6 @@ jobs:
           Set-Service -Name sshd -StartupType Automatic -Status Running
           Set-Service -Name ssh-agent -StartupType Automatic -Status Running
           ssh-keygen -f $Key --% -N "" -p -P ${{ secrets.PRIVATE_KEY }}
-          ssh-add $Key
           if (!(Get-NetFirewallRule -Name 'OpenSSH-Server-In-TCP' -ErrorAction SilentlyContinue | Select-Object Name, Enabled)) {
               Write-Output "Firewall Rule 'OpenSSH-Server-In-TCP' does not exist, creating it..."
               New-NetFirewallRule -Name 'OpenSSH-Server-In-TCP' -DisplayName 'OpenSSH Server (sshd)' -Enabled True -Direction Inbound -Protocol TCP -Action Allow -LocalPort 22
@@ -72,7 +74,6 @@ jobs:
         run: |
           python -m pip install --upgrade pip
           python -m pip install flake8
-          python -m pip install -r requirements-dev.txt
       - name: Lint Trap
         run: |
           # stop the build if there are Python syntax errors or undefined names
@@ -81,7 +82,7 @@ jobs:
           flake8 . --count --exit-zero --max-complexity=14 --max-line-length=80 --statistics
       - name: SFTPretty
         run: |
-          python -m pip install -e .
+          python -m pip install -e .[dev,lint,test]
       - name: Tests
         run: |
           pytest -l -v --tb=long

.pytest.ini

@@ -107,19 +107,36 @@ Example
                    exceptions=socket.timeout, preserve_mtime=True, tries=11)
 
 
++-------------------+--------------------------+
+|                    API Diff                  |
++-------------------+--------------------------+
+|      pysftp       |        sftpretty         |
++===================+==========================+
+|        cwd        |          cd [#]_         |
++-------------------+--------------------------+
+|     makedirs      |         mkdir_p          |
++-------------------+--------------------------+
+|     walktree      |  {local,remote}tree [#]_ |
++-------------------+--------------------------+
+
+.. [#] cwd() is a synonym for chdir(), use cd it's shorter and does the same thing.
+.. [#] Connection.walktree & sftp.walktree with explicit naming.
+.. [*] [path_advance, path_retreat, reparent] no longer needed.
+
+
 Additional Information
 ----------------------
-* Project: https://github.com/byteskeptical/sftpretty
-* Download: https://pypi.python.org/pypi/sftpretty
 * Documentation: https://docs.sftpretty.com
+* Download: https://pypi.python.org/pypi/sftpretty
 * License: BSD
+* Project: https://github.com/byteskeptical/sftpretty
 
 Requirements
 ------------
 paramiko >= 1.17.0
 
 Supports
 --------
-Tested on Python 3.6, 3.7, 3.8, 3.9, 3.10, 3.11
+Tested on Python 3.6, 3.7, 3.8, 3.9, 3.10, 3.11, 3.12
 
 

README.rst

@@ -1,8 +1,15 @@
 Change Log
 ==========
 
-1.1.4 (current, released 2024-1-04)
+1.1.5 (current, released 2024-6-30)
 -----------------------------------
+    * added API diff table
+    * added CnOpts.get_agentkey
+    * adding support/testing for python 3.12
+    * switched to pyproject.toml from setup.py
+
+1.1.4 (released 2024-1-04)
+--------------------------
     * missed the console logger in previous behavior change
 
 1.1.3 (released 2023-12-11)
@@ -36,16 +43,16 @@ Change Log
     * test clean-up and major refactor
 
 1.0.7 (released 2023-02-27)
-------------------------------------
+---------------------------
     * fix regression in put_d
 
 1.0.6 (released 2023-01-15)
-------------------------------------
+---------------------------
     * allow CnOpts knownhost to be set to None directly
     * standardize on using is for None checks 
 
 1.0.5 (released 2022-11-29)
-------------------------------------
+---------------------------
     * added log_level to connection options
     * added compression security option for Transport
     * code optimizations in _start_transport() and _set_authentication()
@@ -54,7 +61,7 @@ Change Log
     * switched to using native logging module instead of paramiko util
 
 1.0.4 (released 2022-09-24)
-------------------------------------
+---------------------------
     * added Windows Pure Path logic in put_d() and put_r() through localtree()
     * fix for regression in _sftp_channel() causing UnboundLocalError
     * improved support for dot notation in known_hosts and private key file

docs/changes.rst

@@ -54,9 +54,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '1.1.4'
+version = '1.1.5'
 # The full version, including alpha/beta/rc tags.
-release = '1.1.4'
+release = '1.1.5'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -172,7 +172,7 @@
 # If true, the index is split into individual pages for each letter.
 # html_split_index = False
 
-# If true, links to the reST sources are added to the pages.
+# If true, links to the REST sources are added to the pages.
 # html_show_sourcelink = True
 
 # If true, "Created using Sphinx" is shown in the HTML footer. Default is True.

docs/conf.py

@@ -1,17 +1,17 @@
 Getting Started
 ===============
 
-While in many ways, sftpretty is just a thin wrapper over paramiko's SFTPClient,
-there are a number of ways that we make it more productive and easier to
-accomplish common, higher-level tasks. The following snippets show where we
-add value to this great module. See the :doc:`sftpretty` docs for a complete
-listing.
+While in many ways, sftpretty is just a thin wrapper around paramiko's
+SFTPClient, there are a number of ways that we make it more productive
+to accomplish common, higher-level tasks. The following snippets show
+where we add value to this great module. See the :doc:`sftpretty` docs
+for a complete listing.
 
 
 :meth:`sftpretty.Connection`
 ----------------------------
 The Connection object is the base of sftpretty. It supports connections via
-username and password.
+username and password or private key.
 
 .. code-block:: python
 
@@ -65,21 +65,25 @@ How about a ``paramiko.AgentKey``? No problem, just set the private_key equal to
 
     import sftpretty
 
-    with sftpretty.Connection('hostname', username='me', private_key=my_agentkey) as sftp:
+    cnopts = sftpretty.CnOpts()
+    keys = cnopts.get_agentkey()
+
+    with sftpretty.Connection('hostname', username='me', private_key=keys[1]) as sftp:
         #
         # ... do sftp operations
         #
 
-The connection object allows the use of an IP address for the ``host`` and the
-ability to optionally set the ``port``, which defaults to 22, otherwise.
+The connection object allows the use of a hostname, IP address, or alias for
+the ``host`` and the ability to optionally set the ``port``, which defaults
+to 22, otherwise.
 
 
 :meth:`sftpretty.CnOpts`
 ------------------------
-You can specify additional connection options using the sftpretty.CnOpts
-object. These options are advanced and not applicable to most uses, because of
-this they have been segmented from the Connection parameter list and made
-available via the CnOpts obj/parameter.
+Additional connection options can be configured using the sftpretty.CnOpts
+object. These are advanced options and are not applicable to most use cases.
+Due to this they have been segmented from the Connection object parameter list
+and made available via a modular object.
 
 OpenSSH-style config objects are supported. The user's default home location
 ``~/.ssh/config`` is always checked though not required unless an alternative
@@ -96,7 +100,7 @@ private key or password authentication.
 
 Config options always take precedence over parameters if both exist. Keep in
 mind there will more than likely be a delta between the security option
-algorithms your verion of SSH supports and those supported by our underlying
+algorithms your verion of SSH supports and those supported by the underlying
 paramiko dependency.
 
 AVAILABLE OPENSSH CONFIG OPTIONS:
@@ -327,7 +331,7 @@ want to return to later.
 :meth:`sftpretty.Connection.chmod`
 ----------------------------------
 :meth:`.chmod` is a wrapper around paramiko's except for the fact it will
-takes an integer representation of the octal mode. No leading 0 or 0o
+take an integer representation of the octal mode. No leading 0 or 0o
 wanted. We know it's suppose to be an octal, but who really remembers that?
 
 This way it is just like a command line ``chmod 644 readme.txt``
@@ -348,15 +352,16 @@ This way it is just like a command line ``chmod 644 readme.txt``
 
 :meth:`sftpretty.Connection.chown`
 ----------------------------------
-Allows you to specify just, gid, uid or both. If either gid or uid is None
-*default*, then sftpretty does a stat to get the current ids and uses that to
-fill in the missing parameter because the underlying paramiko method requires
-that you explicitly set both.
+Allows you to specify just, gid, uid or both as integers. If either gid or uid
+is None *default*, then sftpretty does a stat to get the current ids and uses
+that to fill in the missing parameter because the underlying paramiko method
+requiers that you explicitly set both.
 
-**NOTE** uid and gid are integers and relative to each system. Just because you
-are uid 102 on your local system, a uid of 102 on the remote system most likely
-won't be your login. You will need to do some homework to make sure that you
-are setting these values as you intended.
+.. WARNING::
+    uid and gid are relative to each system. A uid of 102 on your local system,
+    is no assurance of a remote system's user uid even when the usernames
+    match. You will need to do some homework to make sure that you are setting
+    these values as you intended.
 
 
 :attr:`sftpretty.Connection.pwd`
@@ -418,7 +423,7 @@ number to use. Just like the unix cmd, `chmod` you use 744 not 0744 or 0o744.
 -------------------------------------
 A common scenario where you need to create all directories in a path as
 needed, setting their mode, if created. Mode argument works just like
-:meth:`.chmod`, that is an integer representation of the mode you want.
+:meth:`.chmod`, that is an integer representation of the octal mode you want.
 
 .. code-block:: python
 

docs/cookbook.rst

@@ -107,20 +107,37 @@ Example
                    exceptions=socket.timeout, preserve_mtime=True, tries=11)
 
 
++-------------------+--------------------------+
+|                    API Diff                  |
++-------------------+--------------------------+
+|      pysftp       |        sftpretty         |
++===================+==========================+
+|        cwd        |          cd [#]_         |
++-------------------+--------------------------+
+|     makedirs      |         mkdir_p          |
++-------------------+--------------------------+
+|     walktree      |  {local,remote}tree [#]_ |
++-------------------+--------------------------+
+
+.. [#] cwd() is a synonym for chdir(), use cd it's shorter and does the same thing.
+.. [#] Connection.walktree & sftp.walktree with explicit naming.
+.. [*] [path_advance, path_retreat, reparent] no longer needed.
+
+
 Additional Information
 ----------------------
-* Project: https://github.com/byteskeptical/sftpretty
-* Download: https://pypi.python.org/pypi/sftpretty
 * Documentation: https://docs.sftpretty.com
+* Download: https://pypi.python.org/pypi/sftpretty
 * License: BSD
+* Project: https://github.com/byteskeptical/sftpretty
 
 Requirements
 ------------
 paramiko >= 1.17.0
 
 Supports
 --------
-Tested on Python 3.6, 3.7, 3.8, 3.9, 3.10, 3.11
+Tested on Python 3.6, 3.7, 3.8, 3.9, 3.10, 3.11, 3.12
 
 Contents
 --------