Lukasa / requests-ftp

An FTP transport adapter for use with the Python Requests library.
Other
68 stars 25 forks source link

.. image:: https://travis-ci.org/Lukasa/requests-ftp.svg?branch=master :target: https://travis-ci.org/Lukasa/requests-ftp

Requests-FTP

Requests-FTP is an implementation of a very stupid FTP transport adapter for use with the awesome Requests_ Python library.

This library is not intended to be an example of Transport Adapters best practices. This library was cowboyed together in about 4 hours of total work, has no tests, and relies on a few ugly hacks. Instead, it is intended as both a starting point for future development and a useful example for how to implement transport adapters.

Here's how you use it:

.. code-block:: pycon

>>> import requests_ftp
>>> s = requests_ftp.FTPSession()
>>> resp = s.list('ftp://127.0.0.1/', auth=('Lukasa', 'notmypass'))
>>> resp.status_code
'226'
>>> print resp.content
...snip...
>>> resp = s.stor('ftp://127.0.0.1/test.txt', auth=('Lukasa', 'notmypass'),
                   files={'file': open('report.txt', 'rb')})

Features

Almost none!

Does not provide:

Monkey Patching

Sometimes you may want to call a library that uses requests with an ftp URL. First, check whether the library takes a session parameter. If it does, you can use either the FTPSession or FTPAdapter class directly, which is the preferred approach:

.. code-block:: pycon

>>> import requests_ftp
>>> import some_library
>>> s = requests_ftp.FTPSession()
>>> resp = some_library.get('ftp://127.0.0.1/', auth=('Lukasa', 'notmypass'), session=s)

If they do not, either modify the library to add a session parameter, or as an absolute last resort, use the monkeypatch_session function:

.. code-block:: pycon

>>> import requests_ftp
>>> requests_ftp.monkeypatch_session()
>>> import some_library
>>> resp = some_library.get('ftp://127.0.0.1/', auth=('Lukasa', 'notmypass'))

If you expect your code to be used as a library, take particular care to avoid the monkeypatch_session option.

Important Notes

Many corners have been cut in my rush to get this code finished. The most obvious problem is that this code does not have any tests. This is my highest priority for fixing.

More notably, we have the following important caveats:

Contributing

Please do! I would love for this to be developed further by anyone who is interested. Wherever possible, please provide unit tests for your work (yes, this is very much a 'do as I say, not as I do' kind of moment). Don't forget to add your name to AUTHORS.

License

To maximise compatibility with Requests, this code is licensed under the Apache license. See LICENSE for more details.

.. _Requests: https://github.com/kennethreitz/requests