From ccb7a6c2cd22689d363a03da2c7a2bcf4e27a0c8 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Mon, 13 Jan 2014 12:17:46 -0800 Subject: Start fleshing out two-site setup --- sites/_shared_static/logo.png | Bin 0 -> 6401 bytes sites/docs/conf.py | 4 ++ sites/docs/index.rst | 6 ++ sites/main/_templates/rss.xml | 19 ++++++ sites/main/blog.py | 140 ++++++++++++++++++++++++++++++++++++++++ sites/main/blog.rst | 16 +++++ sites/main/blog/first-post.rst | 7 ++ sites/main/blog/second-post.rst | 7 ++ sites/main/conf.py | 4 ++ sites/main/contact.rst | 11 ++++ sites/main/contributing.rst | 19 ++++++ sites/main/index.rst | 31 +++++++++ sites/main/installing.rst | 105 ++++++++++++++++++++++++++++++ sites/shared_conf.py | 56 ++++++++++++++++ 14 files changed, 425 insertions(+) create mode 100644 sites/_shared_static/logo.png create mode 100644 sites/docs/conf.py create mode 100644 sites/docs/index.rst create mode 100644 sites/main/_templates/rss.xml create mode 100644 sites/main/blog.py create mode 100644 sites/main/blog.rst create mode 100644 sites/main/blog/first-post.rst create mode 100644 sites/main/blog/second-post.rst create mode 100644 sites/main/conf.py create mode 100644 sites/main/contact.rst create mode 100644 sites/main/contributing.rst create mode 100644 sites/main/index.rst create mode 100644 sites/main/installing.rst create mode 100644 sites/shared_conf.py (limited to 'sites') diff --git a/sites/_shared_static/logo.png b/sites/_shared_static/logo.png new file mode 100644 index 00000000..bc76697e Binary files /dev/null and b/sites/_shared_static/logo.png differ diff --git a/sites/docs/conf.py b/sites/docs/conf.py new file mode 100644 index 00000000..0c7ffe55 --- /dev/null +++ b/sites/docs/conf.py @@ -0,0 +1,4 @@ +# Obtain shared config values +import os, sys +sys.path.append(os.path.abspath('..')) +from shared_conf import * diff --git a/sites/docs/index.rst b/sites/docs/index.rst new file mode 100644 index 00000000..08b34320 --- /dev/null +++ b/sites/docs/index.rst @@ -0,0 +1,6 @@ +Welcome to Paramiko's documentation! +==================================== + +This site covers Paramiko's usage & API documentation. For basic info on what +Paramiko is, including its public changelog & how the project is maintained, +please see `the main website `_. diff --git a/sites/main/_templates/rss.xml b/sites/main/_templates/rss.xml new file mode 100644 index 00000000..f6f9cbd1 --- /dev/null +++ b/sites/main/_templates/rss.xml @@ -0,0 +1,19 @@ + + + + + {{ title }} + {{ link }} + {{ description }} + {{ date }} + {% for link, title, desc, date in posts %} + + {{ link }} + {{ link }} + <![CDATA[{{ title }}]]> + + {{ date }} + + {% endfor %} + + diff --git a/sites/main/blog.py b/sites/main/blog.py new file mode 100644 index 00000000..3b129ebf --- /dev/null +++ b/sites/main/blog.py @@ -0,0 +1,140 @@ +from collections import namedtuple +from datetime import datetime +import time +import email.utils + +from sphinx.util.compat import Directive +from docutils import nodes + + +class BlogDateDirective(Directive): + """ + Used to parse/attach date info to blog post documents. + + No nodes generated, since none are needed. + """ + has_content = True + + def run(self): + # Tag parent document with parsed date value. + self.state.document.blog_date = datetime.strptime( + self.content[0], "%Y-%m-%d" + ) + # Don't actually insert any nodes, we're already done. + return [] + +class blog_post_list(nodes.General, nodes.Element): + pass + +class BlogPostListDirective(Directive): + """ + Simply spits out a 'blog_post_list' temporary node for replacement. + + Gets replaced at doctree-resolved time - only then will all blog post + documents be written out (& their date directives executed). + """ + def run(self): + return [blog_post_list('')] + + +Post = namedtuple('Post', 'name doc title date opener') + +def get_posts(app): + # Obtain blog posts + post_names = filter(lambda x: x.startswith('blog/'), app.env.found_docs) + posts = map(lambda x: (x, app.env.get_doctree(x)), post_names) + # Obtain common data used for list page & RSS + data = [] + for post, doc in sorted(posts, key=lambda x: x[1].blog_date, reverse=True): + # Welp. No "nice" way to get post title. Thanks Sphinx. + title = doc[0][0][0] + # Date. This may or may not end up reflecting the required + # *input* format, but doing it here gives us flexibility. + date = doc.blog_date + # 1st paragraph as opener. TODO: allow a role or something marking + # where to actually pull from? + opener = doc.traverse(nodes.paragraph)[0] + data.append(Post(post, doc, title, date, opener)) + return data + +def replace_blog_post_lists(app, doctree, fromdocname): + """ + Replace blog_post_list nodes with ordered list-o-links to posts. + """ + # Obtain blog posts + post_names = filter(lambda x: x.startswith('blog/'), app.env.found_docs) + posts = map(lambda x: (x, app.env.get_doctree(x)), post_names) + # Build "list" of links/etc + post_links = [] + for post, doc, title, date, opener in get_posts(app): + # Link itself + uri = app.builder.get_relative_uri(fromdocname, post) + link = nodes.reference('', '', refdocname=post, refuri=uri) + # Title, bolded. TODO: use 'topic' or something maybe? + link.append(nodes.strong('', title)) + date = date.strftime("%Y-%m-%d") + # Meh @ not having great docutils nodes which map to this. + html = '
%s
' % date + timestamp = nodes.raw(text=html, format='html') + # NOTE: may group these within another element later if styling + # necessitates it + group = [timestamp, nodes.paragraph('', '', link), opener] + post_links.extend(group) + + # Replace temp node(s) w/ expanded list-o-links + for node in doctree.traverse(blog_post_list): + node.replace_self(post_links) + +def rss_timestamp(timestamp): + # Use horribly inappropriate module for its magical daylight-savings-aware + # timezone madness. Props to Tinkerer for the idea. + return email.utils.formatdate( + time.mktime(timestamp.timetuple()), + localtime=True + ) + +def generate_rss(app): + # Meh at having to run this subroutine like 3x per build. Not worth trying + # to be clever for now tho. + posts_ = get_posts(app) + # LOL URLs + root = app.config.rss_link + if not root.endswith('/'): + root += '/' + # Oh boy + posts = [ + ( + root + app.builder.get_target_uri(x.name), + x.title, + str(x.opener[0]), # Grab inner text element from paragraph + rss_timestamp(x.date), + ) + for x in posts_ + ] + location = 'blog/rss.xml' + context = { + 'title': app.config.project, + 'link': root, + 'atom': root + location, + 'description': app.config.rss_description, + # 'posts' is sorted by date already + 'date': rss_timestamp(posts_[0].date), + 'posts': posts, + } + yield (location, context, 'rss.xml') + +def setup(app): + # Link in RSS feed back to main website, e.g. 'http://paramiko.org' + app.add_config_value('rss_link', None, '') + # Ditto for RSS description field + app.add_config_value('rss_description', None, '') + # Interprets date metadata in blog post documents + app.add_directive('date', BlogDateDirective) + # Inserts blog post list node (in e.g. a listing page) for replacement + # below + app.add_node(blog_post_list) + app.add_directive('blog-posts', BlogPostListDirective) + # Performs abovementioned replacement + app.connect('doctree-resolved', replace_blog_post_lists) + # Generates RSS page from whole cloth at page generation step + app.connect('html-collect-pages', generate_rss) diff --git a/sites/main/blog.rst b/sites/main/blog.rst new file mode 100644 index 00000000..af9651e4 --- /dev/null +++ b/sites/main/blog.rst @@ -0,0 +1,16 @@ +==== +Blog +==== + +.. blog-posts directive gets replaced with an ordered list of blog posts. + +.. blog-posts:: + + +.. The following toctree ensures blog posts get processed. + +.. toctree:: + :hidden: + :glob: + + blog/* diff --git a/sites/main/blog/first-post.rst b/sites/main/blog/first-post.rst new file mode 100644 index 00000000..7b075073 --- /dev/null +++ b/sites/main/blog/first-post.rst @@ -0,0 +1,7 @@ +=========== +First post! +=========== + +A blog post. + +.. date:: 2013-12-04 diff --git a/sites/main/blog/second-post.rst b/sites/main/blog/second-post.rst new file mode 100644 index 00000000..c4463f33 --- /dev/null +++ b/sites/main/blog/second-post.rst @@ -0,0 +1,7 @@ +=========== +Another one +=========== + +.. date:: 2013-12-05 + +Indeed! diff --git a/sites/main/conf.py b/sites/main/conf.py new file mode 100644 index 00000000..0c7ffe55 --- /dev/null +++ b/sites/main/conf.py @@ -0,0 +1,4 @@ +# Obtain shared config values +import os, sys +sys.path.append(os.path.abspath('..')) +from shared_conf import * diff --git a/sites/main/contact.rst b/sites/main/contact.rst new file mode 100644 index 00000000..b479f170 --- /dev/null +++ b/sites/main/contact.rst @@ -0,0 +1,11 @@ +======= +Contact +======= + +You can get in touch with the developer & user community in any of the +following ways: + +* IRC: ``#paramiko`` on Freenode +* Mailing list: ``paramiko@librelist.com`` (see `the LibreList homepage + `_ for usage details). +* This website's :doc:`blog `. diff --git a/sites/main/contributing.rst b/sites/main/contributing.rst new file mode 100644 index 00000000..b121e64b --- /dev/null +++ b/sites/main/contributing.rst @@ -0,0 +1,19 @@ +============ +Contributing +============ + +How to get the code +=================== + +Our primary Git repository is on Github at `paramiko/paramiko +`; please follow their instruction for +cloning to your local system. (If you intend to submit patches/pull requests, +we recommend forking first, then cloning your fork. Github has excellent +documentation for all this.) + + +How to submit bug reports or new code +===================================== + +Please see `this project-agnostic contribution guide +`_ - we follow it explicitly. diff --git a/sites/main/index.rst b/sites/main/index.rst new file mode 100644 index 00000000..7d203b62 --- /dev/null +++ b/sites/main/index.rst @@ -0,0 +1,31 @@ +Welcome to Paramiko! +==================== + +Paramiko is a Python (2.5+) implementation of the SSHv2 protocol [#]_, +providing both client and server functionality. While it leverages a Python C +extension for low level cryptography (`PyCrypto `_), +Paramiko itself is a pure Python interface around SSH networking concepts. + +This website covers project information for Paramiko such as contribution +guidelines, development roadmap, news/blog, and so forth. Detailed +usage and API documentation can be found at our code documentation site, +`docs.paramiko.org `_. + +.. toctree:: + blog + installing + contributing + contact + + +.. rubric:: Footnotes + +.. [#] + SSH is defined in RFCs + `4251 `_, + `4252 `_, + `4253 `_, and + `4254 `_; + the primary working implementation of the protocol is the `OpenSSH project + `_. Paramiko implements a large portion of the SSH + feature set, but there are occasional gaps. diff --git a/sites/main/installing.rst b/sites/main/installing.rst new file mode 100644 index 00000000..0d4dc1ac --- /dev/null +++ b/sites/main/installing.rst @@ -0,0 +1,105 @@ +========== +Installing +========== + +Paramiko itself +=============== + +The recommended way to get Invoke is to **install the latest stable release** +via `pip `_:: + + $ pip install paramiko + +.. note:: + Users who want the bleeding edge can install the development version via + ``pip install paramiko==dev``. + +We currently support **Python 2.5/2.6/2.7**, with support for Python 3 coming +soon. Users on Python 2.4 or older are urged to upgrade. Paramiko *may* work on +Python 2.4 still, but there is no longer any support guarantee. + +Paramiko has two dependencies: the pure-Python ECDSA module `ecdsa`, and the +PyCrypto C extension. `ecdsa` is easily installable from wherever you +obtained Paramiko's package; PyCrypto may require more work. Read on for +details. + +PyCrypto +======== + +`PyCrypto `_ provides the low-level +(C-based) encryption algorithms we need to implement the SSH protocol. There +are a couple gotchas associated with installing PyCrypto: its compatibility +with Python's package tools, and the fact that it is a C-based extension. + +.. _pycrypto-and-pip: + +Possible gotcha on older Python and/or pip versions +--------------------------------------------------- + +We strongly recommend using ``pip`` to as it is newer and generally better than +``easy_install``. However, a combination of bugs in specific (now rather old) +versions of Python, ``pip`` and PyCrypto can prevent installation of PyCrypto. +Specifically: + +* Python = 2.5.x +* PyCrypto >= 2.1 (required for most modern versions of Paramiko) +* ``pip`` < 0.8.1 + +When all three criteria are met, you may encounter ``No such file or +directory`` IOErrors when trying to ``pip install paramiko`` or ``pip install +PyCrypto``. + +The fix is to make sure at least one of the above criteria is not met, by doing +the following (in order of preference): + +* Upgrade to ``pip`` 0.8.1 or above, e.g. by running ``pip install -U pip``. +* Upgrade to Python 2.6 or above. +* Downgrade to Paramiko 1.7.6 or 1.7.7, which do not require PyCrypto >= 2.1, + and install PyCrypto 2.0.1 (the oldest version on PyPI which works with + Paramiko 1.7.6/1.7.7) + + +C extension +----------- + +Unless you are installing from a precompiled source such as a Debian apt +repository or RedHat RPM, or using :ref:`pypm `, you will also need the +ability to build Python C-based modules from source in order to install +PyCrypto. Users on **Unix-based platforms** such as Ubuntu or Mac OS X will +need the traditional C build toolchain installed (e.g. Developer Tools / XCode +Tools on the Mac, or the ``build-essential`` package on Ubuntu or Debian Linux +-- basically, anything with ``gcc``, ``make`` and so forth) as well as the +Python development libraries, often named ``python-dev`` or similar. + +For **Windows** users we recommend using :ref:`pypm`, installing a C +development environment such as `Cygwin `_ or obtaining a +precompiled Win32 PyCrypto package from `voidspace's Python modules page +`_. + +.. note:: + Some Windows users whose Python is 64-bit have found that the PyCrypto + dependency ``winrandom`` may not install properly, leading to ImportErrors. + In this scenario, you'll probably need to compile ``winrandom`` yourself + via e.g. MS Visual Studio. See `Fabric #194 + `_ for info. + + +.. _pypm: + +ActivePython and PyPM +===================== + +Windows users who already have ActiveState's `ActivePython +`_ distribution installed +may find Paramiko is best installed with `its package manager, PyPM +`_. Below is example output from an +installation of Paramiko via ``pypm``:: + + C:\> pypm install paramiko + The following packages will be installed into "%APPDATA%\Python" (2.7): + paramiko-1.7.8 pycrypto-2.4 + Get: [pypm-free.activestate.com] paramiko 1.7.8 + Get: [pypm-free.activestate.com] pycrypto 2.4 + Installing paramiko-1.7.8 + Installing pycrypto-2.4 + C:\> diff --git a/sites/shared_conf.py b/sites/shared_conf.py new file mode 100644 index 00000000..333db542 --- /dev/null +++ b/sites/shared_conf.py @@ -0,0 +1,56 @@ +from datetime import datetime +import os +import sys + +import alabaster + + +# Add local blog extension +sys.path.append(os.path.abspath('.')) +extensions = ['blog'] +rss_link = 'http://paramiko.org' +rss_description = 'Paramiko project news' + +# Alabaster theme +html_theme_path = [alabaster.get_path()] +# Paths relative to invoking conf.py - not this shared file +html_static_path = ['../_shared_static'] +html_theme = 'alabaster' +html_theme_options = { + 'logo': 'logo.png', + 'logo_name': 'true', + 'description': "A Python implementation of SSHv2.", + 'github_user': 'paramiko', + 'github_repo': 'paramiko', + 'gittip_user': 'bitprophet', + 'analytics_id': 'UA-18486793-2', + + 'link': '#3782BE', + 'link_hover': '#3782BE', + +} +html_sidebars = { + # Landing page (no ToC) + 'index': [ + 'about.html', + 'searchbox.html', + 'donate.html', + ], + # Inner pages get a ToC + '**': [ + 'about.html', + 'localtoc.html', + 'searchbox.html', + 'donate.html', + ] +} + +# Regular settings +project = u'Paramiko' +year = datetime.now().year +copyright = u'%d Jeff Forcier, 2003-2012 Robey Pointer' % year +master_doc = 'index' +templates_path = ['_templates'] +exclude_trees = ['_build'] +source_suffix = '.rst' +default_role = 'obj' -- cgit v1.2.3 From 2da914252064af8dc419b49a423ab57fdb0617c4 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Tue, 21 Jan 2014 16:59:21 -0800 Subject: Rename 'main' doctree to 'www'; refactor sphinx task conf --- sites/main/_templates/rss.xml | 19 ------ sites/main/blog.py | 140 ---------------------------------------- sites/main/blog.rst | 16 ----- sites/main/blog/first-post.rst | 7 -- sites/main/blog/second-post.rst | 7 -- sites/main/conf.py | 4 -- sites/main/contact.rst | 11 ---- sites/main/contributing.rst | 19 ------ sites/main/index.rst | 31 --------- sites/main/installing.rst | 105 ------------------------------ sites/www/_templates/rss.xml | 19 ++++++ sites/www/blog.py | 140 ++++++++++++++++++++++++++++++++++++++++ sites/www/blog.rst | 16 +++++ sites/www/blog/first-post.rst | 7 ++ sites/www/blog/second-post.rst | 7 ++ sites/www/conf.py | 4 ++ sites/www/contact.rst | 11 ++++ sites/www/contributing.rst | 19 ++++++ sites/www/index.rst | 31 +++++++++ sites/www/installing.rst | 105 ++++++++++++++++++++++++++++++ tasks.py | 27 +++++--- 21 files changed, 376 insertions(+), 369 deletions(-) delete mode 100644 sites/main/_templates/rss.xml delete mode 100644 sites/main/blog.py delete mode 100644 sites/main/blog.rst delete mode 100644 sites/main/blog/first-post.rst delete mode 100644 sites/main/blog/second-post.rst delete mode 100644 sites/main/conf.py delete mode 100644 sites/main/contact.rst delete mode 100644 sites/main/contributing.rst delete mode 100644 sites/main/index.rst delete mode 100644 sites/main/installing.rst create mode 100644 sites/www/_templates/rss.xml create mode 100644 sites/www/blog.py create mode 100644 sites/www/blog.rst create mode 100644 sites/www/blog/first-post.rst create mode 100644 sites/www/blog/second-post.rst create mode 100644 sites/www/conf.py create mode 100644 sites/www/contact.rst create mode 100644 sites/www/contributing.rst create mode 100644 sites/www/index.rst create mode 100644 sites/www/installing.rst (limited to 'sites') diff --git a/sites/main/_templates/rss.xml b/sites/main/_templates/rss.xml deleted file mode 100644 index f6f9cbd1..00000000 --- a/sites/main/_templates/rss.xml +++ /dev/null @@ -1,19 +0,0 @@ - - - - - {{ title }} - {{ link }} - {{ description }} - {{ date }} - {% for link, title, desc, date in posts %} - - {{ link }} - {{ link }} - <![CDATA[{{ title }}]]> - - {{ date }} - - {% endfor %} - - diff --git a/sites/main/blog.py b/sites/main/blog.py deleted file mode 100644 index 3b129ebf..00000000 --- a/sites/main/blog.py +++ /dev/null @@ -1,140 +0,0 @@ -from collections import namedtuple -from datetime import datetime -import time -import email.utils - -from sphinx.util.compat import Directive -from docutils import nodes - - -class BlogDateDirective(Directive): - """ - Used to parse/attach date info to blog post documents. - - No nodes generated, since none are needed. - """ - has_content = True - - def run(self): - # Tag parent document with parsed date value. - self.state.document.blog_date = datetime.strptime( - self.content[0], "%Y-%m-%d" - ) - # Don't actually insert any nodes, we're already done. - return [] - -class blog_post_list(nodes.General, nodes.Element): - pass - -class BlogPostListDirective(Directive): - """ - Simply spits out a 'blog_post_list' temporary node for replacement. - - Gets replaced at doctree-resolved time - only then will all blog post - documents be written out (& their date directives executed). - """ - def run(self): - return [blog_post_list('')] - - -Post = namedtuple('Post', 'name doc title date opener') - -def get_posts(app): - # Obtain blog posts - post_names = filter(lambda x: x.startswith('blog/'), app.env.found_docs) - posts = map(lambda x: (x, app.env.get_doctree(x)), post_names) - # Obtain common data used for list page & RSS - data = [] - for post, doc in sorted(posts, key=lambda x: x[1].blog_date, reverse=True): - # Welp. No "nice" way to get post title. Thanks Sphinx. - title = doc[0][0][0] - # Date. This may or may not end up reflecting the required - # *input* format, but doing it here gives us flexibility. - date = doc.blog_date - # 1st paragraph as opener. TODO: allow a role or something marking - # where to actually pull from? - opener = doc.traverse(nodes.paragraph)[0] - data.append(Post(post, doc, title, date, opener)) - return data - -def replace_blog_post_lists(app, doctree, fromdocname): - """ - Replace blog_post_list nodes with ordered list-o-links to posts. - """ - # Obtain blog posts - post_names = filter(lambda x: x.startswith('blog/'), app.env.found_docs) - posts = map(lambda x: (x, app.env.get_doctree(x)), post_names) - # Build "list" of links/etc - post_links = [] - for post, doc, title, date, opener in get_posts(app): - # Link itself - uri = app.builder.get_relative_uri(fromdocname, post) - link = nodes.reference('', '', refdocname=post, refuri=uri) - # Title, bolded. TODO: use 'topic' or something maybe? - link.append(nodes.strong('', title)) - date = date.strftime("%Y-%m-%d") - # Meh @ not having great docutils nodes which map to this. - html = '
%s
' % date - timestamp = nodes.raw(text=html, format='html') - # NOTE: may group these within another element later if styling - # necessitates it - group = [timestamp, nodes.paragraph('', '', link), opener] - post_links.extend(group) - - # Replace temp node(s) w/ expanded list-o-links - for node in doctree.traverse(blog_post_list): - node.replace_self(post_links) - -def rss_timestamp(timestamp): - # Use horribly inappropriate module for its magical daylight-savings-aware - # timezone madness. Props to Tinkerer for the idea. - return email.utils.formatdate( - time.mktime(timestamp.timetuple()), - localtime=True - ) - -def generate_rss(app): - # Meh at having to run this subroutine like 3x per build. Not worth trying - # to be clever for now tho. - posts_ = get_posts(app) - # LOL URLs - root = app.config.rss_link - if not root.endswith('/'): - root += '/' - # Oh boy - posts = [ - ( - root + app.builder.get_target_uri(x.name), - x.title, - str(x.opener[0]), # Grab inner text element from paragraph - rss_timestamp(x.date), - ) - for x in posts_ - ] - location = 'blog/rss.xml' - context = { - 'title': app.config.project, - 'link': root, - 'atom': root + location, - 'description': app.config.rss_description, - # 'posts' is sorted by date already - 'date': rss_timestamp(posts_[0].date), - 'posts': posts, - } - yield (location, context, 'rss.xml') - -def setup(app): - # Link in RSS feed back to main website, e.g. 'http://paramiko.org' - app.add_config_value('rss_link', None, '') - # Ditto for RSS description field - app.add_config_value('rss_description', None, '') - # Interprets date metadata in blog post documents - app.add_directive('date', BlogDateDirective) - # Inserts blog post list node (in e.g. a listing page) for replacement - # below - app.add_node(blog_post_list) - app.add_directive('blog-posts', BlogPostListDirective) - # Performs abovementioned replacement - app.connect('doctree-resolved', replace_blog_post_lists) - # Generates RSS page from whole cloth at page generation step - app.connect('html-collect-pages', generate_rss) diff --git a/sites/main/blog.rst b/sites/main/blog.rst deleted file mode 100644 index af9651e4..00000000 --- a/sites/main/blog.rst +++ /dev/null @@ -1,16 +0,0 @@ -==== -Blog -==== - -.. blog-posts directive gets replaced with an ordered list of blog posts. - -.. blog-posts:: - - -.. The following toctree ensures blog posts get processed. - -.. toctree:: - :hidden: - :glob: - - blog/* diff --git a/sites/main/blog/first-post.rst b/sites/main/blog/first-post.rst deleted file mode 100644 index 7b075073..00000000 --- a/sites/main/blog/first-post.rst +++ /dev/null @@ -1,7 +0,0 @@ -=========== -First post! -=========== - -A blog post. - -.. date:: 2013-12-04 diff --git a/sites/main/blog/second-post.rst b/sites/main/blog/second-post.rst deleted file mode 100644 index c4463f33..00000000 --- a/sites/main/blog/second-post.rst +++ /dev/null @@ -1,7 +0,0 @@ -=========== -Another one -=========== - -.. date:: 2013-12-05 - -Indeed! diff --git a/sites/main/conf.py b/sites/main/conf.py deleted file mode 100644 index 0c7ffe55..00000000 --- a/sites/main/conf.py +++ /dev/null @@ -1,4 +0,0 @@ -# Obtain shared config values -import os, sys -sys.path.append(os.path.abspath('..')) -from shared_conf import * diff --git a/sites/main/contact.rst b/sites/main/contact.rst deleted file mode 100644 index b479f170..00000000 --- a/sites/main/contact.rst +++ /dev/null @@ -1,11 +0,0 @@ -======= -Contact -======= - -You can get in touch with the developer & user community in any of the -following ways: - -* IRC: ``#paramiko`` on Freenode -* Mailing list: ``paramiko@librelist.com`` (see `the LibreList homepage - `_ for usage details). -* This website's :doc:`blog `. diff --git a/sites/main/contributing.rst b/sites/main/contributing.rst deleted file mode 100644 index b121e64b..00000000 --- a/sites/main/contributing.rst +++ /dev/null @@ -1,19 +0,0 @@ -============ -Contributing -============ - -How to get the code -=================== - -Our primary Git repository is on Github at `paramiko/paramiko -`; please follow their instruction for -cloning to your local system. (If you intend to submit patches/pull requests, -we recommend forking first, then cloning your fork. Github has excellent -documentation for all this.) - - -How to submit bug reports or new code -===================================== - -Please see `this project-agnostic contribution guide -`_ - we follow it explicitly. diff --git a/sites/main/index.rst b/sites/main/index.rst deleted file mode 100644 index 7d203b62..00000000 --- a/sites/main/index.rst +++ /dev/null @@ -1,31 +0,0 @@ -Welcome to Paramiko! -==================== - -Paramiko is a Python (2.5+) implementation of the SSHv2 protocol [#]_, -providing both client and server functionality. While it leverages a Python C -extension for low level cryptography (`PyCrypto `_), -Paramiko itself is a pure Python interface around SSH networking concepts. - -This website covers project information for Paramiko such as contribution -guidelines, development roadmap, news/blog, and so forth. Detailed -usage and API documentation can be found at our code documentation site, -`docs.paramiko.org `_. - -.. toctree:: - blog - installing - contributing - contact - - -.. rubric:: Footnotes - -.. [#] - SSH is defined in RFCs - `4251 `_, - `4252 `_, - `4253 `_, and - `4254 `_; - the primary working implementation of the protocol is the `OpenSSH project - `_. Paramiko implements a large portion of the SSH - feature set, but there are occasional gaps. diff --git a/sites/main/installing.rst b/sites/main/installing.rst deleted file mode 100644 index 0d4dc1ac..00000000 --- a/sites/main/installing.rst +++ /dev/null @@ -1,105 +0,0 @@ -========== -Installing -========== - -Paramiko itself -=============== - -The recommended way to get Invoke is to **install the latest stable release** -via `pip `_:: - - $ pip install paramiko - -.. note:: - Users who want the bleeding edge can install the development version via - ``pip install paramiko==dev``. - -We currently support **Python 2.5/2.6/2.7**, with support for Python 3 coming -soon. Users on Python 2.4 or older are urged to upgrade. Paramiko *may* work on -Python 2.4 still, but there is no longer any support guarantee. - -Paramiko has two dependencies: the pure-Python ECDSA module `ecdsa`, and the -PyCrypto C extension. `ecdsa` is easily installable from wherever you -obtained Paramiko's package; PyCrypto may require more work. Read on for -details. - -PyCrypto -======== - -`PyCrypto `_ provides the low-level -(C-based) encryption algorithms we need to implement the SSH protocol. There -are a couple gotchas associated with installing PyCrypto: its compatibility -with Python's package tools, and the fact that it is a C-based extension. - -.. _pycrypto-and-pip: - -Possible gotcha on older Python and/or pip versions ---------------------------------------------------- - -We strongly recommend using ``pip`` to as it is newer and generally better than -``easy_install``. However, a combination of bugs in specific (now rather old) -versions of Python, ``pip`` and PyCrypto can prevent installation of PyCrypto. -Specifically: - -* Python = 2.5.x -* PyCrypto >= 2.1 (required for most modern versions of Paramiko) -* ``pip`` < 0.8.1 - -When all three criteria are met, you may encounter ``No such file or -directory`` IOErrors when trying to ``pip install paramiko`` or ``pip install -PyCrypto``. - -The fix is to make sure at least one of the above criteria is not met, by doing -the following (in order of preference): - -* Upgrade to ``pip`` 0.8.1 or above, e.g. by running ``pip install -U pip``. -* Upgrade to Python 2.6 or above. -* Downgrade to Paramiko 1.7.6 or 1.7.7, which do not require PyCrypto >= 2.1, - and install PyCrypto 2.0.1 (the oldest version on PyPI which works with - Paramiko 1.7.6/1.7.7) - - -C extension ------------ - -Unless you are installing from a precompiled source such as a Debian apt -repository or RedHat RPM, or using :ref:`pypm `, you will also need the -ability to build Python C-based modules from source in order to install -PyCrypto. Users on **Unix-based platforms** such as Ubuntu or Mac OS X will -need the traditional C build toolchain installed (e.g. Developer Tools / XCode -Tools on the Mac, or the ``build-essential`` package on Ubuntu or Debian Linux --- basically, anything with ``gcc``, ``make`` and so forth) as well as the -Python development libraries, often named ``python-dev`` or similar. - -For **Windows** users we recommend using :ref:`pypm`, installing a C -development environment such as `Cygwin `_ or obtaining a -precompiled Win32 PyCrypto package from `voidspace's Python modules page -`_. - -.. note:: - Some Windows users whose Python is 64-bit have found that the PyCrypto - dependency ``winrandom`` may not install properly, leading to ImportErrors. - In this scenario, you'll probably need to compile ``winrandom`` yourself - via e.g. MS Visual Studio. See `Fabric #194 - `_ for info. - - -.. _pypm: - -ActivePython and PyPM -===================== - -Windows users who already have ActiveState's `ActivePython -`_ distribution installed -may find Paramiko is best installed with `its package manager, PyPM -`_. Below is example output from an -installation of Paramiko via ``pypm``:: - - C:\> pypm install paramiko - The following packages will be installed into "%APPDATA%\Python" (2.7): - paramiko-1.7.8 pycrypto-2.4 - Get: [pypm-free.activestate.com] paramiko 1.7.8 - Get: [pypm-free.activestate.com] pycrypto 2.4 - Installing paramiko-1.7.8 - Installing pycrypto-2.4 - C:\> diff --git a/sites/www/_templates/rss.xml b/sites/www/_templates/rss.xml new file mode 100644 index 00000000..f6f9cbd1 --- /dev/null +++ b/sites/www/_templates/rss.xml @@ -0,0 +1,19 @@ + + + + + {{ title }} + {{ link }} + {{ description }} + {{ date }} + {% for link, title, desc, date in posts %} + + {{ link }} + {{ link }} + <![CDATA[{{ title }}]]> + + {{ date }} + + {% endfor %} + + diff --git a/sites/www/blog.py b/sites/www/blog.py new file mode 100644 index 00000000..3b129ebf --- /dev/null +++ b/sites/www/blog.py @@ -0,0 +1,140 @@ +from collections import namedtuple +from datetime import datetime +import time +import email.utils + +from sphinx.util.compat import Directive +from docutils import nodes + + +class BlogDateDirective(Directive): + """ + Used to parse/attach date info to blog post documents. + + No nodes generated, since none are needed. + """ + has_content = True + + def run(self): + # Tag parent document with parsed date value. + self.state.document.blog_date = datetime.strptime( + self.content[0], "%Y-%m-%d" + ) + # Don't actually insert any nodes, we're already done. + return [] + +class blog_post_list(nodes.General, nodes.Element): + pass + +class BlogPostListDirective(Directive): + """ + Simply spits out a 'blog_post_list' temporary node for replacement. + + Gets replaced at doctree-resolved time - only then will all blog post + documents be written out (& their date directives executed). + """ + def run(self): + return [blog_post_list('')] + + +Post = namedtuple('Post', 'name doc title date opener') + +def get_posts(app): + # Obtain blog posts + post_names = filter(lambda x: x.startswith('blog/'), app.env.found_docs) + posts = map(lambda x: (x, app.env.get_doctree(x)), post_names) + # Obtain common data used for list page & RSS + data = [] + for post, doc in sorted(posts, key=lambda x: x[1].blog_date, reverse=True): + # Welp. No "nice" way to get post title. Thanks Sphinx. + title = doc[0][0][0] + # Date. This may or may not end up reflecting the required + # *input* format, but doing it here gives us flexibility. + date = doc.blog_date + # 1st paragraph as opener. TODO: allow a role or something marking + # where to actually pull from? + opener = doc.traverse(nodes.paragraph)[0] + data.append(Post(post, doc, title, date, opener)) + return data + +def replace_blog_post_lists(app, doctree, fromdocname): + """ + Replace blog_post_list nodes with ordered list-o-links to posts. + """ + # Obtain blog posts + post_names = filter(lambda x: x.startswith('blog/'), app.env.found_docs) + posts = map(lambda x: (x, app.env.get_doctree(x)), post_names) + # Build "list" of links/etc + post_links = [] + for post, doc, title, date, opener in get_posts(app): + # Link itself + uri = app.builder.get_relative_uri(fromdocname, post) + link = nodes.reference('', '', refdocname=post, refuri=uri) + # Title, bolded. TODO: use 'topic' or something maybe? + link.append(nodes.strong('', title)) + date = date.strftime("%Y-%m-%d") + # Meh @ not having great docutils nodes which map to this. + html = '
%s
' % date + timestamp = nodes.raw(text=html, format='html') + # NOTE: may group these within another element later if styling + # necessitates it + group = [timestamp, nodes.paragraph('', '', link), opener] + post_links.extend(group) + + # Replace temp node(s) w/ expanded list-o-links + for node in doctree.traverse(blog_post_list): + node.replace_self(post_links) + +def rss_timestamp(timestamp): + # Use horribly inappropriate module for its magical daylight-savings-aware + # timezone madness. Props to Tinkerer for the idea. + return email.utils.formatdate( + time.mktime(timestamp.timetuple()), + localtime=True + ) + +def generate_rss(app): + # Meh at having to run this subroutine like 3x per build. Not worth trying + # to be clever for now tho. + posts_ = get_posts(app) + # LOL URLs + root = app.config.rss_link + if not root.endswith('/'): + root += '/' + # Oh boy + posts = [ + ( + root + app.builder.get_target_uri(x.name), + x.title, + str(x.opener[0]), # Grab inner text element from paragraph + rss_timestamp(x.date), + ) + for x in posts_ + ] + location = 'blog/rss.xml' + context = { + 'title': app.config.project, + 'link': root, + 'atom': root + location, + 'description': app.config.rss_description, + # 'posts' is sorted by date already + 'date': rss_timestamp(posts_[0].date), + 'posts': posts, + } + yield (location, context, 'rss.xml') + +def setup(app): + # Link in RSS feed back to main website, e.g. 'http://paramiko.org' + app.add_config_value('rss_link', None, '') + # Ditto for RSS description field + app.add_config_value('rss_description', None, '') + # Interprets date metadata in blog post documents + app.add_directive('date', BlogDateDirective) + # Inserts blog post list node (in e.g. a listing page) for replacement + # below + app.add_node(blog_post_list) + app.add_directive('blog-posts', BlogPostListDirective) + # Performs abovementioned replacement + app.connect('doctree-resolved', replace_blog_post_lists) + # Generates RSS page from whole cloth at page generation step + app.connect('html-collect-pages', generate_rss) diff --git a/sites/www/blog.rst b/sites/www/blog.rst new file mode 100644 index 00000000..af9651e4 --- /dev/null +++ b/sites/www/blog.rst @@ -0,0 +1,16 @@ +==== +Blog +==== + +.. blog-posts directive gets replaced with an ordered list of blog posts. + +.. blog-posts:: + + +.. The following toctree ensures blog posts get processed. + +.. toctree:: + :hidden: + :glob: + + blog/* diff --git a/sites/www/blog/first-post.rst b/sites/www/blog/first-post.rst new file mode 100644 index 00000000..7b075073 --- /dev/null +++ b/sites/www/blog/first-post.rst @@ -0,0 +1,7 @@ +=========== +First post! +=========== + +A blog post. + +.. date:: 2013-12-04 diff --git a/sites/www/blog/second-post.rst b/sites/www/blog/second-post.rst new file mode 100644 index 00000000..c4463f33 --- /dev/null +++ b/sites/www/blog/second-post.rst @@ -0,0 +1,7 @@ +=========== +Another one +=========== + +.. date:: 2013-12-05 + +Indeed! diff --git a/sites/www/conf.py b/sites/www/conf.py new file mode 100644 index 00000000..0c7ffe55 --- /dev/null +++ b/sites/www/conf.py @@ -0,0 +1,4 @@ +# Obtain shared config values +import os, sys +sys.path.append(os.path.abspath('..')) +from shared_conf import * diff --git a/sites/www/contact.rst b/sites/www/contact.rst new file mode 100644 index 00000000..b479f170 --- /dev/null +++ b/sites/www/contact.rst @@ -0,0 +1,11 @@ +======= +Contact +======= + +You can get in touch with the developer & user community in any of the +following ways: + +* IRC: ``#paramiko`` on Freenode +* Mailing list: ``paramiko@librelist.com`` (see `the LibreList homepage + `_ for usage details). +* This website's :doc:`blog `. diff --git a/sites/www/contributing.rst b/sites/www/contributing.rst new file mode 100644 index 00000000..b121e64b --- /dev/null +++ b/sites/www/contributing.rst @@ -0,0 +1,19 @@ +============ +Contributing +============ + +How to get the code +=================== + +Our primary Git repository is on Github at `paramiko/paramiko +`; please follow their instruction for +cloning to your local system. (If you intend to submit patches/pull requests, +we recommend forking first, then cloning your fork. Github has excellent +documentation for all this.) + + +How to submit bug reports or new code +===================================== + +Please see `this project-agnostic contribution guide +`_ - we follow it explicitly. diff --git a/sites/www/index.rst b/sites/www/index.rst new file mode 100644 index 00000000..7d203b62 --- /dev/null +++ b/sites/www/index.rst @@ -0,0 +1,31 @@ +Welcome to Paramiko! +==================== + +Paramiko is a Python (2.5+) implementation of the SSHv2 protocol [#]_, +providing both client and server functionality. While it leverages a Python C +extension for low level cryptography (`PyCrypto `_), +Paramiko itself is a pure Python interface around SSH networking concepts. + +This website covers project information for Paramiko such as contribution +guidelines, development roadmap, news/blog, and so forth. Detailed +usage and API documentation can be found at our code documentation site, +`docs.paramiko.org `_. + +.. toctree:: + blog + installing + contributing + contact + + +.. rubric:: Footnotes + +.. [#] + SSH is defined in RFCs + `4251 `_, + `4252 `_, + `4253 `_, and + `4254 `_; + the primary working implementation of the protocol is the `OpenSSH project + `_. Paramiko implements a large portion of the SSH + feature set, but there are occasional gaps. diff --git a/sites/www/installing.rst b/sites/www/installing.rst new file mode 100644 index 00000000..0d4dc1ac --- /dev/null +++ b/sites/www/installing.rst @@ -0,0 +1,105 @@ +========== +Installing +========== + +Paramiko itself +=============== + +The recommended way to get Invoke is to **install the latest stable release** +via `pip `_:: + + $ pip install paramiko + +.. note:: + Users who want the bleeding edge can install the development version via + ``pip install paramiko==dev``. + +We currently support **Python 2.5/2.6/2.7**, with support for Python 3 coming +soon. Users on Python 2.4 or older are urged to upgrade. Paramiko *may* work on +Python 2.4 still, but there is no longer any support guarantee. + +Paramiko has two dependencies: the pure-Python ECDSA module `ecdsa`, and the +PyCrypto C extension. `ecdsa` is easily installable from wherever you +obtained Paramiko's package; PyCrypto may require more work. Read on for +details. + +PyCrypto +======== + +`PyCrypto `_ provides the low-level +(C-based) encryption algorithms we need to implement the SSH protocol. There +are a couple gotchas associated with installing PyCrypto: its compatibility +with Python's package tools, and the fact that it is a C-based extension. + +.. _pycrypto-and-pip: + +Possible gotcha on older Python and/or pip versions +--------------------------------------------------- + +We strongly recommend using ``pip`` to as it is newer and generally better than +``easy_install``. However, a combination of bugs in specific (now rather old) +versions of Python, ``pip`` and PyCrypto can prevent installation of PyCrypto. +Specifically: + +* Python = 2.5.x +* PyCrypto >= 2.1 (required for most modern versions of Paramiko) +* ``pip`` < 0.8.1 + +When all three criteria are met, you may encounter ``No such file or +directory`` IOErrors when trying to ``pip install paramiko`` or ``pip install +PyCrypto``. + +The fix is to make sure at least one of the above criteria is not met, by doing +the following (in order of preference): + +* Upgrade to ``pip`` 0.8.1 or above, e.g. by running ``pip install -U pip``. +* Upgrade to Python 2.6 or above. +* Downgrade to Paramiko 1.7.6 or 1.7.7, which do not require PyCrypto >= 2.1, + and install PyCrypto 2.0.1 (the oldest version on PyPI which works with + Paramiko 1.7.6/1.7.7) + + +C extension +----------- + +Unless you are installing from a precompiled source such as a Debian apt +repository or RedHat RPM, or using :ref:`pypm `, you will also need the +ability to build Python C-based modules from source in order to install +PyCrypto. Users on **Unix-based platforms** such as Ubuntu or Mac OS X will +need the traditional C build toolchain installed (e.g. Developer Tools / XCode +Tools on the Mac, or the ``build-essential`` package on Ubuntu or Debian Linux +-- basically, anything with ``gcc``, ``make`` and so forth) as well as the +Python development libraries, often named ``python-dev`` or similar. + +For **Windows** users we recommend using :ref:`pypm`, installing a C +development environment such as `Cygwin `_ or obtaining a +precompiled Win32 PyCrypto package from `voidspace's Python modules page +`_. + +.. note:: + Some Windows users whose Python is 64-bit have found that the PyCrypto + dependency ``winrandom`` may not install properly, leading to ImportErrors. + In this scenario, you'll probably need to compile ``winrandom`` yourself + via e.g. MS Visual Studio. See `Fabric #194 + `_ for info. + + +.. _pypm: + +ActivePython and PyPM +===================== + +Windows users who already have ActiveState's `ActivePython +`_ distribution installed +may find Paramiko is best installed with `its package manager, PyPM +`_. Below is example output from an +installation of Paramiko via ``pypm``:: + + C:\> pypm install paramiko + The following packages will be installed into "%APPDATA%\Python" (2.7): + paramiko-1.7.8 pycrypto-2.4 + Get: [pypm-free.activestate.com] paramiko 1.7.8 + Get: [pypm-free.activestate.com] pycrypto 2.4 + Installing paramiko-1.7.8 + Installing pycrypto-2.4 + C:\> diff --git a/tasks.py b/tasks.py index 3326a773..c7164158 100644 --- a/tasks.py +++ b/tasks.py @@ -1,16 +1,23 @@ +from os.path import join + from invoke import Collection -from invocations import docs, testing +from invocations import docs as _docs, testing + +d = 'sites' -# Usage doc/API site -api = Collection.from_module(docs, name='docs', config={ - 'sphinx.source': 'sites/docs', - 'sphinx.target': 'sites/docs/_build', +# Usage doc/API site (published as docs.paramiko.org) +path = join(d, 'docs') +docs = Collection.from_module(_docs, name='docs', config={ + 'sphinx.source': path, + 'sphinx.target': join(path, '_build'), }) -# Main/about/changelog site -main = Collection.from_module(docs, name='main', config={ - 'sphinx.source': 'sites/main', - 'sphinx.target': 'sites/main/_build', + +# Main/about/changelog site ((www.)?paramiko.org) +path = join(d, 'www') +www = Collection.from_module(_docs, name='www', config={ + 'sphinx.source': path, + 'sphinx.target': join(path, '_build'), }) -ns = Collection(testing.test, docs=api, main=main) +ns = Collection(testing.test, docs=docs, www=www) -- cgit v1.2.3 From 5a1f927310414ca47408c3f2f81a0b43beb8cb19 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Wed, 22 Jan 2014 10:55:39 -0800 Subject: Blog only used/exists in www, don't import it in docs site --- sites/shared_conf.py | 6 ------ sites/www/conf.py | 7 +++++++ 2 files changed, 7 insertions(+), 6 deletions(-) (limited to 'sites') diff --git a/sites/shared_conf.py b/sites/shared_conf.py index 333db542..89e0a56d 100644 --- a/sites/shared_conf.py +++ b/sites/shared_conf.py @@ -5,12 +5,6 @@ import sys import alabaster -# Add local blog extension -sys.path.append(os.path.abspath('.')) -extensions = ['blog'] -rss_link = 'http://paramiko.org' -rss_description = 'Paramiko project news' - # Alabaster theme html_theme_path = [alabaster.get_path()] # Paths relative to invoking conf.py - not this shared file diff --git a/sites/www/conf.py b/sites/www/conf.py index 0c7ffe55..e504ec7b 100644 --- a/sites/www/conf.py +++ b/sites/www/conf.py @@ -2,3 +2,10 @@ import os, sys sys.path.append(os.path.abspath('..')) from shared_conf import * + +# Add local blog extension +sys.path.append(os.path.abspath('.')) +extensions = ['blog'] +rss_link = 'http://paramiko.org' +rss_description = 'Paramiko project news' + -- cgit v1.2.3 From 03768eadcafbbab93f9c5c6c67479e97249e7a09 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Wed, 22 Jan 2014 12:48:32 -0800 Subject: Migrate 1.10.x NEWS entries to Sphinx changelog --- dev-requirements.txt | 1 + sites/www/changelog.rst | 77 +++++++++++++++++++++++++++++++++++++++++++++++++ sites/www/conf.py | 4 +++ sites/www/index.rst | 5 ++-- 4 files changed, 85 insertions(+), 2 deletions(-) create mode 100644 sites/www/changelog.rst (limited to 'sites') diff --git a/dev-requirements.txt b/dev-requirements.txt index 59a1f144..a2b9a4e8 100644 --- a/dev-requirements.txt +++ b/dev-requirements.txt @@ -4,3 +4,4 @@ invoke>=0.6.1 invocations>=0.4.4 sphinx>=1.1.3 alabaster>=0.1.0 +releases>=0.2.4 diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst new file mode 100644 index 00000000..d83de54b --- /dev/null +++ b/sites/www/changelog.rst @@ -0,0 +1,77 @@ +========= +Changelog +========= + +* :release:`1.10.6 <2014-01-21>` +* :bug:`193` (and its attentant PRs :issue:`230` & :issue:`253`): Fix SSH agent + problems present on Windows. Thanks to David Hobbs for initial report and to + Aarni Koskela & Olle Lundberg for the patches. +* :release:`1.10.5 <2014-01-08>` +* :bug:`176`: Fix AttributeError bugs in known_hosts file (re)loading. Thanks + to Nathan Scowcroft for the patch & Martin Blumenstingl for the initial test + case. +* :release:`1.10.4 <2013-09-27>` +* :bug:`179`: Fix a missing variable causing errors when an ssh_config file has + a non-default AddressFamily set. Thanks to Ed Marshall & Tomaz Muraus for + catch & patch. +* :bug:`200`: Fix an exception-causing typo in `demo_simple.py`. Thanks to Alex + Buchanan for catch & Dave Foster for patch. +* :bug:`199`: Typo fix in the license header cross-project. Thanks to Armin + Ronacher for catch & patch. +* :release:`1.10.3 <2013-09-20>` +* :bug:`162`: Clean up HMAC module import to avoid deadlocks in certain uses of + SSHClient. Thanks to Gernot Hillier for the catch & suggested fix. +* :bug:`36`: Fix the port-forwarding demo to avoid file descriptor errors. + Thanks to Jonathan Halcrow for catch & patch. +* :bug:`168`: Update config handling to properly handle multiple 'localforward' + and 'remoteforward' keys. Thanks to Emre Yılmaz for the patch. +* :release:`1.10.2 <2013-07-26>` +* :bug:`153`, :issue:`67`: Warn on parse failure when reading known_hosts + file. Thanks to `@glasserc` for patch. +* :bug:`146`: Indentation fixes for readability. Thanks to Abhinav Upadhyay for + catch & patch. +* :release:`1.10.1 <2013-04-05>` +* :bug:`142`: (`Fabric #811 `_) + SFTP put of empty file will still return the attributes of the put file. + Thanks to Jason R. Coombs for the patch. +* :bug:`154`: (`Fabric #876 `_) + Forwarded SSH agent connections left stale local pipes lying around, which + could cause local (and sometimes remote or network) resource starvation when + running many agent-using remote commands. Thanks to Kevin Tegtmeier for catch + & patch. +* :release:`1.10.0 <2013-03-01>` +* :feature:`66`: Batch SFTP writes to help speed up file transfers. Thanks to + Olle Lundberg for the patch. +* :bug:`133 major`: Fix handling of window-change events to be on-spec and not + attempt to wait for a response from the remote sshd; this fixes problems with + less common targets such as some Cisco devices. Thanks to Phillip Heller for + catch & patch. +* :feature:`93`: Overhaul SSH config parsing to be in line with `man + ssh_config` (& the behavior of `ssh` itself), including addition of parameter + expansion within config values. Thanks to Olle Lundberg for the patch. +* :feature:`110`: Honor SSH config `AddressFamily` setting when looking up + local host's FQDN. Thanks to John Hensley for the patch. +* :feature:`128`: Defer FQDN resolution until needed, when parsing SSH config + files. Thanks to Parantapa Bhattacharya for catch & patch. +* :bug:`102 major`: Forego random padding for packets when running under + `*-ctr` ciphers. This corrects some slowdowns on platforms where random byte + generation is inefficient (e.g. Windows). Thanks to `@warthog618` for catch + & patch, and Michael van der Kolff for code/technique review. +* :feature:`127`: Turn `SFTPFile` into a context manager. Thanks to Michael + Williamson for the patch. +* :feature:`116`: Limit `Message.get_bytes` to an upper bound of 1MB to protect + against potential DoS vectors. Thanks to `@mvschaik` for catch & patch. +* :feature:`115`: Add convenience `get_pty` kwarg to `Client.exec_command` so + users not manually controlling a channel object can still toggle PTY + creation. Thanks to Michael van der Kolff for the patch. +* :feature:`71`: Add `SFTPClient.putfo` and `.getfo` methods to allow direct + uploading/downloading of file-like objects. Thanks to Eric Buehl for the + patch. +* :feature:`113`: Add `timeout` parameter to `SSHClient.exec_command` for + easier setting of the command's internal channel object's timeout. Thanks to + Cernov Vladimir for the patch. +* :support:`94`: Remove duplication of SSH port constant. Thanks to Olle + Lundberg for the catch. +* :feature:`80`: Expose the internal "is closed" property of the file transfer + class `BufferedFile` as `.closed`, better conforming to Python's file + interface. Thanks to `@smunaut` and James Hiscock for catch & patch. diff --git a/sites/www/conf.py b/sites/www/conf.py index e504ec7b..c144b5b4 100644 --- a/sites/www/conf.py +++ b/sites/www/conf.py @@ -9,3 +9,7 @@ extensions = ['blog'] rss_link = 'http://paramiko.org' rss_description = 'Paramiko project news' +# Add Releases changelog extension +extensions.append('releases') +releases_release_uri = "https://github.com/paramiko/paramiko/tree/%s" +releases_issue_uri = "https://github.com/paramiko/paramiko/issues/%s" diff --git a/sites/www/index.rst b/sites/www/index.rst index 7d203b62..f8db6fd0 100644 --- a/sites/www/index.rst +++ b/sites/www/index.rst @@ -6,13 +6,14 @@ providing both client and server functionality. While it leverages a Python C extension for low level cryptography (`PyCrypto `_), Paramiko itself is a pure Python interface around SSH networking concepts. -This website covers project information for Paramiko such as contribution -guidelines, development roadmap, news/blog, and so forth. Detailed +This website covers project information for Paramiko such as the changelog, +contribution guidelines, development roadmap, news/blog, and so forth. Detailed usage and API documentation can be found at our code documentation site, `docs.paramiko.org `_. .. toctree:: blog + changelog installing contributing contact -- cgit v1.2.3 From dde21a7de09bd92a6a362a26009a56a942b3d246 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Wed, 22 Jan 2014 14:25:08 -0800 Subject: Nuke extraneous colons, add 'major' notes --- sites/www/changelog.rst | 48 ++++++++++++++++++++++++------------------------ 1 file changed, 24 insertions(+), 24 deletions(-) (limited to 'sites') diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst index d83de54b..bba78949 100644 --- a/sites/www/changelog.rst +++ b/sites/www/changelog.rst @@ -7,71 +7,71 @@ Changelog problems present on Windows. Thanks to David Hobbs for initial report and to Aarni Koskela & Olle Lundberg for the patches. * :release:`1.10.5 <2014-01-08>` -* :bug:`176`: Fix AttributeError bugs in known_hosts file (re)loading. Thanks +* :bug:`176` Fix AttributeError bugs in known_hosts file (re)loading. Thanks to Nathan Scowcroft for the patch & Martin Blumenstingl for the initial test case. * :release:`1.10.4 <2013-09-27>` -* :bug:`179`: Fix a missing variable causing errors when an ssh_config file has +* :bug:`179` Fix a missing variable causing errors when an ssh_config file has a non-default AddressFamily set. Thanks to Ed Marshall & Tomaz Muraus for catch & patch. -* :bug:`200`: Fix an exception-causing typo in `demo_simple.py`. Thanks to Alex +* :bug:`200` Fix an exception-causing typo in `demo_simple.py`. Thanks to Alex Buchanan for catch & Dave Foster for patch. -* :bug:`199`: Typo fix in the license header cross-project. Thanks to Armin +* :bug:`199` Typo fix in the license header cross-project. Thanks to Armin Ronacher for catch & patch. * :release:`1.10.3 <2013-09-20>` -* :bug:`162`: Clean up HMAC module import to avoid deadlocks in certain uses of +* :bug:`162` Clean up HMAC module import to avoid deadlocks in certain uses of SSHClient. Thanks to Gernot Hillier for the catch & suggested fix. -* :bug:`36`: Fix the port-forwarding demo to avoid file descriptor errors. +* :bug:`36` Fix the port-forwarding demo to avoid file descriptor errors. Thanks to Jonathan Halcrow for catch & patch. -* :bug:`168`: Update config handling to properly handle multiple 'localforward' +* :bug:`168` Update config handling to properly handle multiple 'localforward' and 'remoteforward' keys. Thanks to Emre Yılmaz for the patch. * :release:`1.10.2 <2013-07-26>` -* :bug:`153`, :issue:`67`: Warn on parse failure when reading known_hosts +* :bug:`153` (also :issue:`67`) Warn on parse failure when reading known_hosts file. Thanks to `@glasserc` for patch. -* :bug:`146`: Indentation fixes for readability. Thanks to Abhinav Upadhyay for +* :bug:`146` Indentation fixes for readability. Thanks to Abhinav Upadhyay for catch & patch. * :release:`1.10.1 <2013-04-05>` -* :bug:`142`: (`Fabric #811 `_) +* :bug:`142` (`Fabric #811 `_) SFTP put of empty file will still return the attributes of the put file. Thanks to Jason R. Coombs for the patch. -* :bug:`154`: (`Fabric #876 `_) +* :bug:`154` (`Fabric #876 `_) Forwarded SSH agent connections left stale local pipes lying around, which could cause local (and sometimes remote or network) resource starvation when running many agent-using remote commands. Thanks to Kevin Tegtmeier for catch & patch. * :release:`1.10.0 <2013-03-01>` -* :feature:`66`: Batch SFTP writes to help speed up file transfers. Thanks to +* :feature:`66` Batch SFTP writes to help speed up file transfers. Thanks to Olle Lundberg for the patch. -* :bug:`133 major`: Fix handling of window-change events to be on-spec and not +* :bug:`133 major` Fix handling of window-change events to be on-spec and not attempt to wait for a response from the remote sshd; this fixes problems with less common targets such as some Cisco devices. Thanks to Phillip Heller for catch & patch. -* :feature:`93`: Overhaul SSH config parsing to be in line with `man +* :feature:`93` Overhaul SSH config parsing to be in line with `man ssh_config` (& the behavior of `ssh` itself), including addition of parameter expansion within config values. Thanks to Olle Lundberg for the patch. -* :feature:`110`: Honor SSH config `AddressFamily` setting when looking up +* :feature:`110` Honor SSH config `AddressFamily` setting when looking up local host's FQDN. Thanks to John Hensley for the patch. -* :feature:`128`: Defer FQDN resolution until needed, when parsing SSH config +* :feature:`128` Defer FQDN resolution until needed, when parsing SSH config files. Thanks to Parantapa Bhattacharya for catch & patch. -* :bug:`102 major`: Forego random padding for packets when running under +* :bug:`102 major` Forego random padding for packets when running under `*-ctr` ciphers. This corrects some slowdowns on platforms where random byte generation is inefficient (e.g. Windows). Thanks to `@warthog618` for catch & patch, and Michael van der Kolff for code/technique review. -* :feature:`127`: Turn `SFTPFile` into a context manager. Thanks to Michael +* :feature:`127` Turn `SFTPFile` into a context manager. Thanks to Michael Williamson for the patch. -* :feature:`116`: Limit `Message.get_bytes` to an upper bound of 1MB to protect +* :feature:`116` Limit `Message.get_bytes` to an upper bound of 1MB to protect against potential DoS vectors. Thanks to `@mvschaik` for catch & patch. -* :feature:`115`: Add convenience `get_pty` kwarg to `Client.exec_command` so +* :feature:`115` Add convenience `get_pty` kwarg to `Client.exec_command` so users not manually controlling a channel object can still toggle PTY creation. Thanks to Michael van der Kolff for the patch. -* :feature:`71`: Add `SFTPClient.putfo` and `.getfo` methods to allow direct +* :feature:`71` Add `SFTPClient.putfo` and `.getfo` methods to allow direct uploading/downloading of file-like objects. Thanks to Eric Buehl for the patch. -* :feature:`113`: Add `timeout` parameter to `SSHClient.exec_command` for +* :feature:`113` Add `timeout` parameter to `SSHClient.exec_command` for easier setting of the command's internal channel object's timeout. Thanks to Cernov Vladimir for the patch. -* :support:`94`: Remove duplication of SSH port constant. Thanks to Olle +* :support:`94` Remove duplication of SSH port constant. Thanks to Olle Lundberg for the catch. -* :feature:`80`: Expose the internal "is closed" property of the file transfer +* :feature:`80` Expose the internal "is closed" property of the file transfer class `BufferedFile` as `.closed`, better conforming to Python's file interface. Thanks to `@smunaut` and James Hiscock for catch & patch. -- cgit v1.2.3 From 24635609dc5ab8aff2e7fa3f34c4993cbc424579 Mon Sep 17 00:00:00 2001 From: Olle Lundberg Date: Thu, 23 Jan 2014 11:32:59 +0100 Subject: Epydoc -> Sphinx. --- paramiko/__init__.py | 22 +- paramiko/agent.py | 20 +- paramiko/auth_handler.py | 2 +- paramiko/buffered_pipe.py | 52 ++--- paramiko/channel.py | 418 ++++++++++++++++++------------------ paramiko/client.py | 210 +++++++++--------- paramiko/config.py | 38 ++-- paramiko/dsskey.py | 16 +- paramiko/file.py | 104 ++++----- paramiko/hostkeys.py | 84 ++++---- paramiko/kex_gex.py | 2 +- paramiko/message.py | 98 ++++----- paramiko/packet.py | 20 +- paramiko/pkey.py | 210 +++++++++--------- paramiko/primes.py | 2 +- paramiko/proxy.py | 22 +- paramiko/resource.py | 18 +- paramiko/rsakey.py | 16 +- paramiko/server.py | 514 ++++++++++++++++++++++---------------------- paramiko/sftp_attr.py | 26 +-- paramiko/sftp_client.py | 380 ++++++++++++++++----------------- paramiko/sftp_file.py | 144 ++++++------- paramiko/sftp_handle.py | 80 +++---- paramiko/sftp_server.py | 48 ++--- paramiko/sftp_si.py | 220 +++++++++---------- paramiko/ssh_exception.py | 42 ++-- paramiko/transport.py | 534 +++++++++++++++++++++++----------------------- paramiko/util.py | 42 ++-- sites/docs/api.rst | 8 + sites/docs/conf.py | 3 + 30 files changed, 1703 insertions(+), 1692 deletions(-) create mode 100644 sites/docs/api.rst (limited to 'sites') diff --git a/paramiko/__init__.py b/paramiko/__init__.py index 924e8bb5..c6f555a9 100644 --- a/paramiko/__init__.py +++ b/paramiko/__init__.py @@ -17,35 +17,35 @@ # 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA. """ -I{Paramiko} (a combination of the esperanto words for "paranoid" and "friend") +Paramiko (a combination of the esperanto words for "paranoid" and "friend") is a module for python 2.5 or greater that implements the SSH2 protocol for secure (encrypted and authenticated) connections to remote machines. Unlike SSL (aka TLS), the SSH2 protocol does not require hierarchical certificates signed by a powerful central authority. You may know SSH2 as the protocol that -replaced C{telnet} and C{rsh} for secure access to remote shells, but the +replaced ``telnet`` and ``rsh`` for secure access to remote shells, but the protocol also includes the ability to open arbitrary channels to remote -services across an encrypted tunnel. (This is how C{sftp} works, for example.) +services across an encrypted tunnel. (This is how ``sftp`` works, for example.) -The high-level client API starts with creation of an L{SSHClient} object. +The high-level client API starts with creation of an :class:`SSHClient` object. For more direct control, pass a socket (or socket-like object) to a -L{Transport}, and use L{start_server } or -L{start_client } to negoatite +:class:`Transport`, and use :class:`start_server ` or +:class:`start_client ` to negoatite with the remote host as either a server or client. As a client, you are responsible for authenticating using a password or private key, and checking -the server's host key. I{(Key signature and verification is done by paramiko, +the server's host key. (Key signature and verification is done by paramiko, but you will need to provide private keys and check that the content of a -public key matches what you expected to see.)} As a server, you are +public key matches what you expected to see.) As a server, you are responsible for deciding which users, passwords, and keys to allow, and what kind of channels to allow. -Once you have finished, either side may request flow-controlled L{Channel}s to -the other side, which are python objects that act like sockets, but send and +Once you have finished, either side may request flow-controlled :class:`channels ` +to the other side, which are python objects that act like sockets, but send and receive data over the encrypted session. Paramiko is written entirely in python (no C or platform-dependent code) and is released under the GNU Lesser General Public License (LGPL). -Website: U{https://github.com/paramiko/paramiko/} +Website: https://github.com/paramiko/paramiko/ """ import sys diff --git a/paramiko/agent.py b/paramiko/agent.py index 23a5a2e4..a09851bc 100644 --- a/paramiko/agent.py +++ b/paramiko/agent.py @@ -44,7 +44,7 @@ class AgentSSH(object): """ Client interface for using private keys from an SSH agent running on the local machine. If an SSH agent is running, this class can be used to - connect to it and retreive L{PKey} objects which can be used when + connect to it and retreive :class:`PKey` objects which can be used when attempting to authenticate to remote SSH servers. Because the SSH agent protocol uses environment variables and unix-domain @@ -61,8 +61,8 @@ class AgentSSH(object): no SSH agent was running (or it couldn't be contacted), an empty list will be returned. - @return: a list of keys available on the SSH agent - @rtype: tuple of L{AgentKey} + :return: a list of keys available on the SSH agent + :rtype: tuple of :class:`AgentKey` """ return self._keys @@ -238,9 +238,9 @@ class AgentClientProxy(object): class AgentServerProxy(AgentSSH): """ - @param t : transport used for the Forward for SSH Agent communication + :param t : transport used for the Forward for SSH Agent communication - @raise SSHException: mostly if we lost the agent + :raises SSHException: mostly if we lost the agent """ def __init__(self, t): AgentSSH.__init__(self) @@ -276,8 +276,8 @@ class AgentServerProxy(AgentSSH): """ Helper for the environnement under unix - @return: the SSH_AUTH_SOCK Environnement variables - @rtype: dict + :return: the SSH_AUTH_SOCK Environnement variables + :rtype: dict """ env = {} env['SSH_AUTH_SOCK'] = self._get_filename() @@ -307,7 +307,7 @@ class Agent(AgentSSH): """ Client interface for using private keys from an SSH agent running on the local machine. If an SSH agent is running, this class can be used to - connect to it and retreive L{PKey} objects which can be used when + connect to it and retreive :class:`PKey` objects which can be used when attempting to authenticate to remote SSH servers. Because the SSH agent protocol uses environment variables and unix-domain @@ -318,10 +318,10 @@ class Agent(AgentSSH): def __init__(self): """ Open a session with the local machine's SSH agent, if one is running. - If no agent is running, initialization will succeed, but L{get_keys} + If no agent is running, initialization will succeed, but :class:`get_keys` will return an empty tuple. - @raise SSHException: if an SSH agent is found, but speaks an + :raises SSHException: if an SSH agent is found, but speaks an incompatible protocol """ AgentSSH.__init__(self) diff --git a/paramiko/auth_handler.py b/paramiko/auth_handler.py index acb7c8b8..56bd37d5 100644 --- a/paramiko/auth_handler.py +++ b/paramiko/auth_handler.py @@ -17,7 +17,7 @@ # 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA. """ -L{AuthHandler} +:class:`AuthHandler` """ import threading diff --git a/paramiko/buffered_pipe.py b/paramiko/buffered_pipe.py index 4ef5cf74..23ed9f44 100644 --- a/paramiko/buffered_pipe.py +++ b/paramiko/buffered_pipe.py @@ -29,7 +29,7 @@ import time class PipeTimeout (IOError): """ - Indicates that a timeout was reached on a read from a L{BufferedPipe}. + Indicates that a timeout was reached on a read from a :class:`BufferedPipe`. """ pass @@ -38,7 +38,7 @@ class BufferedPipe (object): """ A buffer that obeys normal read (with timeout) & close semantics for a file or socket, but is fed data from another thread. This is used by - L{Channel}. + :class:`Channel`. """ def __init__(self): @@ -54,8 +54,8 @@ class BufferedPipe (object): buffer has been closed), the event will be set. When no data is ready, the event will be cleared. - @param event: the event to set/clear - @type event: Event + :param event: the event to set/clear + :type event: Event """ self._event = event if len(self._buffer) > 0: @@ -68,8 +68,8 @@ class BufferedPipe (object): Feed new data into this pipe. This method is assumed to be called from a separate thread, so synchronization is done. - @param data: the data to add - @type data: str + :param data: the data to add + :type data: str """ self._lock.acquire() try: @@ -83,12 +83,12 @@ class BufferedPipe (object): def read_ready(self): """ Returns true if data is buffered and ready to be read from this - feeder. A C{False} result does not mean that the feeder has closed; + feeder. A ``False`` result does not mean that the feeder has closed; it means you may need to wait before more data arrives. - @return: C{True} if a L{read} call would immediately return at least - one byte; C{False} otherwise. - @rtype: bool + :return: ``True`` if a :class:`read` call would immediately return at least + one byte; ``False`` otherwise. + :rtype: bool """ self._lock.acquire() try: @@ -102,23 +102,23 @@ class BufferedPipe (object): """ Read data from the pipe. The return value is a string representing the data received. The maximum amount of data to be received at once - is specified by C{nbytes}. If a string of length zero is returned, + is specified by ``nbytes``. If a string of length zero is returned, the pipe has been closed. - The optional C{timeout} argument can be a nonnegative float expressing - seconds, or C{None} for no timeout. If a float is given, a - C{PipeTimeout} will be raised if the timeout period value has + The optional ``timeout`` argument can be a nonnegative float expressing + seconds, or ``None`` for no timeout. If a float is given, a + ``PipeTimeout`` will be raised if the timeout period value has elapsed before any data arrives. - @param nbytes: maximum number of bytes to read - @type nbytes: int - @param timeout: maximum seconds to wait (or C{None}, the default, to + :param nbytes: maximum number of bytes to read + :type nbytes: int + :param timeout: maximum seconds to wait (or ``None``, the default, to wait forever) - @type timeout: float - @return: data - @rtype: str + :type timeout: float + :return: data + :rtype: str - @raise PipeTimeout: if a timeout was specified and no data was ready + :raises PipeTimeout: if a timeout was specified and no data was ready before that timeout """ out = '' @@ -158,8 +158,8 @@ class BufferedPipe (object): """ Clear out the buffer and return all data that was in it. - @return: any data that was in the buffer prior to clearing it out - @rtype: str + :return: any data that was in the buffer prior to clearing it out + :rtype: str """ self._lock.acquire() try: @@ -173,7 +173,7 @@ class BufferedPipe (object): def close(self): """ - Close this pipe object. Future calls to L{read} after the buffer + Close this pipe object. Future calls to :class:`read` after the buffer has been emptied will return immediately with an empty string. """ self._lock.acquire() @@ -189,8 +189,8 @@ class BufferedPipe (object): """ Return the number of bytes buffered. - @return: number of bytes bufferes - @rtype: int + :return: number of bytes bufferes + :rtype: int """ self._lock.acquire() try: diff --git a/paramiko/channel.py b/paramiko/channel.py index c680e44b..7a430435 100644 --- a/paramiko/channel.py +++ b/paramiko/channel.py @@ -42,7 +42,7 @@ MIN_PACKET_SIZE = 1024 class Channel (object): """ - A secure tunnel across an SSH L{Transport}. A Channel is meant to behave + A secure tunnel across an SSH :class:`Transport`. A Channel is meant to behave like a socket, and has an API that should be indistinguishable from the python socket API. @@ -51,20 +51,20 @@ class Channel (object): you any more data until you read some of it. (This won't affect other channels on the same transport -- all channels on a single transport are flow-controlled independently.) Similarly, if the server isn't reading - data you send, calls to L{send} may block, unless you set a timeout. This + data you send, calls to :class:`send` may block, unless you set a timeout. This is exactly like a normal network socket, so it shouldn't be too surprising. """ def __init__(self, chanid): """ Create a new channel. The channel is not associated with any - particular session or L{Transport} until the Transport attaches it. + particular session or :class:`Transport` until the Transport attaches it. Normally you would only call this method from the constructor of a - subclass of L{Channel}. + subclass of :class:`Channel`. - @param chanid: the ID of this channel, as passed by an existing - L{Transport}. - @type chanid: int + :param chanid: the ID of this channel, as passed by an existing + :class:`Transport`. + :type chanid: int """ self.chanid = chanid self.remote_chanid = 0 @@ -105,7 +105,7 @@ class Channel (object): """ Return a string representation of this object, for debugging. - @rtype: str + :rtype: str """ out = '' diff --git a/paramiko/client.py b/paramiko/client.py index be896091..19a09c2d 100644 --- a/paramiko/client.py +++ b/paramiko/client.py @@ -17,7 +17,7 @@ # 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA. """ -L{SSHClient}. +:class:`SSHClient`. """ from binascii import hexlify @@ -40,19 +40,19 @@ from paramiko.util import retry_on_signal class MissingHostKeyPolicy (object): """ - Interface for defining the policy that L{SSHClient} should use when the + Interface for defining the policy that :class:`SSHClient` should use when the SSH server's hostname is not in either the system host keys or the application's keys. Pre-made classes implement policies for automatically - adding the key to the application's L{HostKeys} object (L{AutoAddPolicy}), - and for automatically rejecting the key (L{RejectPolicy}). + adding the key to the application's :class:`HostKeys` object (:class:`AutoAddPolicy`), + and for automatically rejecting the key (:class:`RejectPolicy`). This function may be used to ask the user to verify the key, for example. """ def missing_host_key(self, client, hostname, key): """ - Called when an L{SSHClient} receives a server key for a server that - isn't in either the system or local L{HostKeys} object. To accept + Called when an :class:`SSHClient` receives a server key for a server that + isn't in either the system or local :class:`HostKeys` object. To accept the key, simply return. To reject, raised an exception (which will be passed to the calling application). """ @@ -62,7 +62,7 @@ class MissingHostKeyPolicy (object): class AutoAddPolicy (MissingHostKeyPolicy): """ Policy for automatically adding the hostname and new host key to the - local L{HostKeys} object, and saving it. This is used by L{SSHClient}. + local :class:`HostKeys` object, and saving it. This is used by :class:`SSHClient`. """ def missing_host_key(self, client, hostname, key): @@ -76,7 +76,7 @@ class AutoAddPolicy (MissingHostKeyPolicy): class RejectPolicy (MissingHostKeyPolicy): """ Policy for automatically rejecting the unknown hostname & key. This is - used by L{SSHClient}. + used by :class:`SSHClient`. """ def missing_host_key(self, client, hostname, key): @@ -88,7 +88,7 @@ class RejectPolicy (MissingHostKeyPolicy): class WarningPolicy (MissingHostKeyPolicy): """ Policy for logging a python-style warning for an unknown host key, but - accepting it. This is used by L{SSHClient}. + accepting it. This is used by :class:`SSHClient`. """ def missing_host_key(self, client, hostname, key): warnings.warn('Unknown %s host key for %s: %s' % @@ -98,7 +98,7 @@ class WarningPolicy (MissingHostKeyPolicy): class SSHClient (object): """ A high-level representation of a session with an SSH server. This class - wraps L{Transport}, L{Channel}, and L{SFTPClient} to take care of most + wraps :class:`Transport`, :class:`Channel`, and :class:`SFTPClient` to take care of most aspects of authenticating and opening channels. A typical use case is:: client = SSHClient() @@ -110,7 +110,7 @@ class SSHClient (object): checking. The default mechanism is to try to use local key files or an SSH agent (if one is running). - @since: 1.6 + .. versionadded:: 1.6 """ def __init__(self): @@ -128,21 +128,21 @@ class SSHClient (object): def load_system_host_keys(self, filename=None): """ Load host keys from a system (read-only) file. Host keys read with - this method will not be saved back by L{save_host_keys}. + this method will not be saved back by :class:`save_host_keys`. This method can be called multiple times. Each new set of host keys will be merged with the existing set (new replacing old if there are conflicts). - If C{filename} is left as C{None}, an attempt will be made to read + If ``filename`` is left as ``None``, an attempt will be made to read keys from the user's local "known hosts" file, as used by OpenSSH, and no exception will be raised if the file can't be read. This is probably only useful on posix. - @param filename: the filename to read, or C{None} - @type filename: str + :param filename: the filename to read, or ``None`` + :type filename: str - @raise IOError: if a filename was provided and the file could not be + :raises IOError: if a filename was provided and the file could not be read """ if filename is None: @@ -158,19 +158,19 @@ class SSHClient (object): def load_host_keys(self, filename): """ Load host keys from a local host-key file. Host keys read with this - method will be checked I{after} keys loaded via L{load_system_host_keys}, - but will be saved back by L{save_host_keys} (so they can be modified). - The missing host key policy L{AutoAddPolicy} adds keys to this set and + method will be checked after keys loaded via :class:`load_system_host_keys`, + but will be saved back by :class:`save_host_keys` (so they can be modified). + The missing host key policy :class:`AutoAddPolicy` adds keys to this set and saves them, when connecting to a previously-unknown server. This method can be called multiple times. Each new set of host keys will be merged with the existing set (new replacing old if there are conflicts). When automatically saving, the last hostname is used. - @param filename: the filename to read - @type filename: str + :param filename: the filename to read + :type filename: str - @raise IOError: if the filename could not be read + :raises IOError: if the filename could not be read """ self._host_keys_filename = filename self._host_keys.load(filename) @@ -178,13 +178,13 @@ class SSHClient (object): def save_host_keys(self, filename): """ Save the host keys back to a file. Only the host keys loaded with - L{load_host_keys} (plus any added directly) will be saved -- not any - host keys loaded with L{load_system_host_keys}. + :class:`load_host_keys` (plus any added directly) will be saved -- not any + host keys loaded with :class:`load_system_host_keys`. - @param filename: the filename to save to - @type filename: str + :param filename: the filename to save to + :type filename: str - @raise IOError: if the file could not be written + :raises IOError: if the file could not be written """ # update local host keys from file (in case other SSH clients @@ -200,34 +200,34 @@ class SSHClient (object): def get_host_keys(self): """ - Get the local L{HostKeys} object. This can be used to examine the + Get the local :class:`HostKeys` object. This can be used to examine the local host keys or change them. - @return: the local host keys - @rtype: L{HostKeys} + :return: the local host keys + :rtype: :class:`HostKeys` """ return self._host_keys def set_log_channel(self, name): """ - Set the channel for logging. The default is C{"paramiko.transport"} + Set the channel for logging. The default is ``"paramiko.transport"`` but it can be set to anything you want. - @param name: new channel name for logging - @type name: str + :param name: new channel name for logging + :type name: str """ self._log_channel = name def set_missing_host_key_policy(self, policy): """ Set the policy to use when connecting to a server that doesn't have a - host key in either the system or local L{HostKeys} objects. The - default policy is to reject all unknown servers (using L{RejectPolicy}). - You may substitute L{AutoAddPolicy} or write your own policy class. + host key in either the system or local :class:`HostKeys` objects. The + default policy is to reject all unknown servers (using :class:`RejectPolicy`). + You may substitute :class:`AutoAddPolicy` or write your own policy class. - @param policy: the policy to use when receiving a host key from a + :param policy: the policy to use when receiving a host key from a previously-unknown server - @type policy: L{MissingHostKeyPolicy} + :type policy: :class:`MissingHostKeyPolicy` """ self._policy = policy @@ -236,56 +236,56 @@ class SSHClient (object): compress=False, sock=None): """ Connect to an SSH server and authenticate to it. The server's host key - is checked against the system host keys (see L{load_system_host_keys}) - and any local host keys (L{load_host_keys}). If the server's hostname + is checked against the system host keys (see :class:`load_system_host_keys`) + and any local host keys (:class:`load_host_keys`). If the server's hostname is not found in either set of host keys, the missing host key policy - is used (see L{set_missing_host_key_policy}). The default policy is - to reject the key and raise an L{SSHException}. + is used (see :class:`set_missing_host_key_policy`). The default policy is + to reject the key and raise an :class:`SSHException`. Authentication is attempted in the following order of priority: - - The C{pkey} or C{key_filename} passed in (if any) + - The ``pkey`` or ``key_filename`` passed in (if any) - Any key we can find through an SSH agent - - Any "id_rsa" or "id_dsa" key discoverable in C{~/.ssh/} + - Any "id_rsa" or "id_dsa" key discoverable in ``~/.ssh/`` - Plain username/password auth, if a password was given If a private key requires a password to unlock it, and a password is passed in, that password will be used to attempt to unlock the key. - @param hostname: the server to connect to - @type hostname: str - @param port: the server port to connect to - @type port: int - @param username: the username to authenticate as (defaults to the + :param hostname: the server to connect to + :type hostname: str + :param port: the server port to connect to + :type port: int + :param username: the username to authenticate as (defaults to the current local username) - @type username: str - @param password: a password to use for authentication or for unlocking + :type username: str + :param password: a password to use for authentication or for unlocking a private key - @type password: str - @param pkey: an optional private key to use for authentication - @type pkey: L{PKey} - @param key_filename: the filename, or list of filenames, of optional + :type password: str + :param pkey: an optional private key to use for authentication + :type pkey: :class:`PKey` + :param key_filename: the filename, or list of filenames, of optional private key(s) to try for authentication - @type key_filename: str or list(str) - @param timeout: an optional timeout (in seconds) for the TCP connect - @type timeout: float - @param allow_agent: set to False to disable connecting to the SSH agent - @type allow_agent: bool - @param look_for_keys: set to False to disable searching for discoverable - private key files in C{~/.ssh/} - @type look_for_keys: bool - @param compress: set to True to turn on compression - @type compress: bool - @param sock: an open socket or socket-like object (such as a - L{Channel}) to use for communication to the target host - @type sock: socket - - @raise BadHostKeyException: if the server's host key could not be + :type key_filename: str or list(str) + :param timeout: an optional timeout (in seconds) for the TCP connect + :type timeout: float + :param allow_agent: set to False to disable connecting to the SSH agent + :type allow_agent: bool + :param look_for_keys: set to False to disable searching for discoverable + private key files in ``~/.ssh/`` + :type look_for_keys: bool + :param compress: set to True to turn on compression + :type compress: bool + :param sock: an open socket or socket-like object (such as a + :class:`Channel`) to use for communication to the target host + :type sock: socket + + :raises BadHostKeyException: if the server's host key could not be verified - @raise AuthenticationException: if authentication failed - @raise SSHException: if there was any other error connecting or + :raises AuthenticationException: if authentication failed + :raises SSHException: if there was any other error connecting or establishing an SSH session - @raise socket.error: if a socket error occurred while connecting + :raises socket.error: if a socket error occurred while connecting """ if not sock: for (family, socktype, proto, canonname, sockaddr) in socket.getaddrinfo(hostname, port, socket.AF_UNSPEC, socket.SOCK_STREAM): @@ -343,7 +343,7 @@ class SSHClient (object): def close(self): """ - Close this SSHClient and its underlying L{Transport}. + Close this SSHClient and its underlying :class:`Transport`. """ if self._transport is None: return @@ -356,21 +356,21 @@ class SSHClient (object): def exec_command(self, command, bufsize=-1, timeout=None, get_pty=False): """ - Execute a command on the SSH server. A new L{Channel} is opened and + Execute a command on the SSH server. A new :class:`Channel` is opened and the requested command is executed. The command's input and output - streams are returned as python C{file}-like objects representing + streams are returned as python ``file``-like objects representing stdin, stdout, and stderr. - @param command: the command to execute - @type command: str - @param bufsize: interpreted the same way as by the built-in C{file()} function in python - @type bufsize: int - @param timeout: set command's channel timeout. See L{Channel.settimeout}.settimeout - @type timeout: int - @return: the stdin, stdout, and stderr of the executing command - @rtype: tuple(L{ChannelFile}, L{ChannelFile}, L{ChannelFile}) + :param command: the command to execute + :type command: str + :param bufsize: interpreted the same way as by the built-in ``file()`` function in python + :type bufsize: int + :param timeout: set command's channel timeout. See :class:`Channel.settimeout`.settimeout + :type timeout: int + :return: the stdin, stdout, and stderr of the executing command + :rtype: tuple(:class:`ChannelFile`, :class:`ChannelFile`, :class:`ChannelFile`) - @raise SSHException: if the server fails to execute the command + :raises SSHException: if the server fails to execute the command """ chan = self._transport.open_session() if(get_pty): @@ -385,24 +385,24 @@ class SSHClient (object): def invoke_shell(self, term='vt100', width=80, height=24, width_pixels=0, height_pixels=0): """ - Start an interactive shell session on the SSH server. A new L{Channel} + Start an interactive shell session on the SSH server. A new :class:`Channel` is opened and connected to a pseudo-terminal using the requested terminal type and size. - @param term: the terminal type to emulate (for example, C{"vt100"}) - @type term: str - @param width: the width (in characters) of the terminal window - @type width: int - @param height: the height (in characters) of the terminal window - @type height: int - @param width_pixels: the width (in pixels) of the terminal window - @type width_pixels: int - @param height_pixels: the height (in pixels) of the terminal window - @type height_pixels: int - @return: a new channel connected to the remote shell - @rtype: L{Channel} - - @raise SSHException: if the server fails to invoke a shell + :param term: the terminal type to emulate (for example, ``"vt100"``) + :type term: str + :param width: the width (in characters) of the terminal window + :type width: int + :param height: the height (in characters) of the terminal window + :type height: int + :param width_pixels: the width (in pixels) of the terminal window + :type width_pixels: int + :param height_pixels: the height (in pixels) of the terminal window + :type height_pixels: int + :return: a new channel connected to the remote shell + :rtype: :class:`Channel` + + :raises SSHException: if the server fails to invoke a shell """ chan = self._transport.open_session() chan.get_pty(term, width, height, width_pixels, height_pixels) @@ -413,19 +413,19 @@ class SSHClient (object): """ Open an SFTP session on the SSH server. - @return: a new SFTP session object - @rtype: L{SFTPClient} + :return: a new SFTP session object + :rtype: :class:`SFTPClient` """ return self._transport.open_sftp_client() def get_transport(self): """ - Return the underlying L{Transport} object for this SSH connection. + Return the underlying :class:`Transport` object for this SSH connection. This can be used to perform lower-level tasks, like opening specific kinds of channels. - @return: the Transport for this connection - @rtype: L{Transport} + :return: the Transport for this connection + :rtype: :class:`Transport` """ return self._transport diff --git a/paramiko/config.py b/paramiko/config.py index 1705de76..05f59813 100644 --- a/paramiko/config.py +++ b/paramiko/config.py @@ -18,7 +18,7 @@ # 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA. """ -L{SSHConfig}. +:class:`SSHConfig`. """ import fnmatch @@ -87,12 +87,12 @@ class LazyFqdn(object): class SSHConfig (object): """ Representation of config information as stored in the format used by - OpenSSH. Queries can be made via L{lookup}. The format is described in - OpenSSH's C{ssh_config} man page. This class is provided primarily as a + OpenSSH. Queries can be made via :class:`lookup`. The format is described in + OpenSSH's ``ssh_config`` man page. This class is provided primarily as a convenience to posix users (since the OpenSSH format is a de-facto standard on posix) but should work fine on Windows too. - @since: 1.6 + .. versionadded:: 1.6 """ def __init__(self): @@ -105,8 +105,8 @@ class SSHConfig (object): """ Read an OpenSSH config from the given file object. - @param file_obj: a file-like object to read the config file from - @type file_obj: file + :param file_obj: a file-like object to read the config file from + :type file_obj: file """ host = {"host": ['*'], "config": {}} for line in file_obj: @@ -152,20 +152,20 @@ class SSHConfig (object): """ Return a dict of config options for a given hostname. - The host-matching rules of OpenSSH's C{ssh_config} man page are used, + The host-matching rules of OpenSSH's ``ssh_config`` man page are used, which means that all configuration options from matching host specifications are merged, with more specific hostmasks taking - precedence. In other words, if C{"Port"} is set under C{"Host *"} - and also C{"Host *.example.com"}, and the lookup is for - C{"ssh.example.com"}, then the port entry for C{"Host *.example.com"} + precedence. In other words, if ``"Port"`` is set under ``"Host *"`` + and also ``"Host *.example.com"``, and the lookup is for + ``"ssh.example.com"``, then the port entry for ``"Host *.example.com"`` will win out. The keys in the returned dict are all normalized to lowercase (look for - C{"port"}, not C{"Port"}. The values are processed according to the - rules for substitution variable expansion in C{ssh_config}. + ``"port"``, not ``"Port"``. The values are processed according to the + rules for substitution variable expansion in ``ssh_config``. - @param hostname: the hostname to lookup - @type hostname: str + :param hostname: the hostname to lookup + :type hostname: str """ matches = [config for config in self._config if @@ -199,13 +199,13 @@ class SSHConfig (object): Return a dict of config options with expanded substitutions for a given hostname. - Please refer to man C{ssh_config} for the parameters that + Please refer to man ``ssh_config`` for the parameters that are replaced. - @param config: the config for the hostname - @type hostname: dict - @param hostname: the hostname that the config belongs to - @type hostname: str + :param config: the config for the hostname + :type hostname: dict + :param hostname: the hostname that the config belongs to + :type hostname: str """ if 'hostname' in config: diff --git a/paramiko/dsskey.py b/paramiko/dsskey.py index f6ecb2a7..2d9f6cef 100644 --- a/paramiko/dsskey.py +++ b/paramiko/dsskey.py @@ -17,7 +17,7 @@ # 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA. """ -L{DSSKey} +:class:`DSSKey` """ from Crypto.PublicKey import DSA @@ -153,13 +153,13 @@ class DSSKey (PKey): Generate a new private DSS key. This factory function can be used to generate a new host key or authentication key. - @param bits: number of bits the generated key should be. - @type bits: int - @param progress_func: an optional function to call at key points in - key generation (used by C{pyCrypto.PublicKey}). - @type progress_func: function - @return: new private key - @rtype: L{DSSKey} + :param bits: number of bits the generated key should be. + :type bits: int + :param progress_func: an optional function to call at key points in + key generation (used by ``pyCrypto.PublicKey``). + :type progress_func: function + :return: new private key + :rtype: :class:`DSSKey` """ dsa = DSA.generate(bits, rng.read, progress_func) key = DSSKey(vals=(dsa.p, dsa.q, dsa.g, dsa.y)) diff --git a/paramiko/file.py b/paramiko/file.py index 5fd81cfe..58d9f8bb 100644 --- a/paramiko/file.py +++ b/paramiko/file.py @@ -67,10 +67,10 @@ class BufferedFile (object): file. This iterator happens to return the file itself, since a file is its own iterator. - @raise ValueError: if the file is closed. + :raises ValueError: if the file is closed. - @return: an interator. - @rtype: iterator + :return: an interator. + :rtype: iterator """ if self._closed: raise ValueError('I/O operation on closed file') @@ -94,14 +94,14 @@ class BufferedFile (object): def next(self): """ - Returns the next line from the input, or raises L{StopIteration} when + Returns the next line from the input, or raises :class:`StopIteration` when EOF is hit. Unlike python file objects, it's okay to mix calls to - C{next} and L{readline}. + ``next`` and :class:`readline`. - @raise StopIteration: when the end of the file is reached. + :raises StopIteration: when the end of the file is reached. - @return: a line read from the file. - @rtype: str + :return: a line read from the file. + :rtype: str """ line = self.readline() if not line: @@ -110,15 +110,15 @@ class BufferedFile (object): def read(self, size=None): """ - Read at most C{size} bytes from the file (less if we hit the end of the - file first). If the C{size} argument is negative or omitted, read all + Read at most ``size`` bytes from the file (less if we hit the end of the + file first). If the ``size`` argument is negative or omitted, read all the remaining data in the file. - @param size: maximum number of bytes to read - @type size: int - @return: data read from the file, or an empty string if EOF was + :param size: maximum number of bytes to read + :type size: int + :return: data read from the file, or an empty string if EOF was encountered immediately - @rtype: str + :rtype: str """ if self._closed: raise IOError('File is closed') @@ -171,14 +171,14 @@ class BufferedFile (object): incomplete line may be returned. An empty string is returned only when EOF is encountered immediately. - @note: Unlike stdio's C{fgets()}, the returned string contains null - characters (C{'\\0'}) if they occurred in the input. + .. note:: Unlike stdio's ``fgets()``, the returned string contains null + characters (``'\\0'``) if they occurred in the input. - @param size: maximum length of returned string. - @type size: int - @return: next line of the file, or an empty string if the end of the + :param size: maximum length of returned string. + :type size: int + :return: next line of the file, or an empty string if the end of the file has been reached. - @rtype: str + :rtype: str """ # it's almost silly how complex this function is. if self._closed: @@ -243,15 +243,15 @@ class BufferedFile (object): def readlines(self, sizehint=None): """ - Read all remaining lines using L{readline} and return them as a list. - If the optional C{sizehint} argument is present, instead of reading up + Read all remaining lines using :class:`readline` and return them as a list. + If the optional ``sizehint`` argument is present, instead of reading up to EOF, whole lines totalling approximately sizehint bytes (possibly after rounding up to an internal buffer size) are read. - @param sizehint: desired maximum number of bytes to read. - @type sizehint: int - @return: list of lines read from the file. - @rtype: list + :param sizehint: desired maximum number of bytes to read. + :type sizehint: int + :return: list of lines read from the file. + :rtype: list """ lines = [] bytes = 0 @@ -267,21 +267,21 @@ class BufferedFile (object): def seek(self, offset, whence=0): """ - Set the file's current position, like stdio's C{fseek}. Not all file + Set the file's current position, like stdio's ``fseek``. Not all file objects support seeking. - @note: If a file is opened in append mode (C{'a'} or C{'a+'}), any seek + .. note:: If a file is opened in append mode (``'a'`` or ``'a+'``), any seek operations will be undone at the next write (as the file position will move back to the end of the file). - @param offset: position to move to within the file, relative to - C{whence}. - @type offset: int - @param whence: type of movement: 0 = absolute; 1 = relative to the + :param offset: position to move to within the file, relative to + ``whence``. + :type offset: int + :param whence: type of movement: 0 = absolute; 1 = relative to the current position; 2 = relative to the end of the file. - @type whence: int + :type whence: int - @raise IOError: if the file doesn't support random access. + :raises IOError: if the file doesn't support random access. """ raise IOError('File does not support seeking.') @@ -291,20 +291,20 @@ class BufferedFile (object): useful if the underlying file doesn't support random access, or was opened in append mode. - @return: file position (in bytes). - @rtype: int + :return: file position (in bytes). + :rtype: int """ return self._pos def write(self, data): """ - Write data to the file. If write buffering is on (C{bufsize} was + Write data to the file. If write buffering is on (``bufsize`` was specified and non-zero), some or all of the data may not actually be - written yet. (Use L{flush} or L{close} to force buffered data to be + written yet. (Use :class:`flush` or :class:`close` to force buffered data to be written out.) - @param data: data to write. - @type data: str + :param data: data to write. + :type data: str """ if self._closed: raise IOError('File is closed') @@ -334,11 +334,11 @@ class BufferedFile (object): """ Write a sequence of strings to the file. The sequence can be any iterable object producing strings, typically a list of strings. (The - name is intended to match L{readlines}; C{writelines} does not add line + name is intended to match :class:`readlines`; ``writelines`` does not add line separators.) - @param sequence: an iterable sequence of strings. - @type sequence: sequence + :param sequence: an iterable sequence of strings. + :type sequence: sequence """ for line in sequence: self.write(line) @@ -346,11 +346,11 @@ class BufferedFile (object): def xreadlines(self): """ - Identical to C{iter(f)}. This is a deprecated file interface that + Identical to ``iter(f)``. This is a deprecated file interface that predates python iterator support. - @return: an iterator. - @rtype: iterator + :return: an iterator. + :rtype: iterator """ return self @@ -364,25 +364,25 @@ class BufferedFile (object): def _read(self, size): """ - I{(subclass override)} - Read data from the stream. Return C{None} or raise C{EOFError} to + (subclass override) + Read data from the stream. Return ``None`` or raise ``EOFError`` to indicate EOF. """ raise EOFError() def _write(self, data): """ - I{(subclass override)} + (subclass override) Write data into the stream. """ raise IOError('write not implemented') def _get_size(self): """ - I{(subclass override)} - Return the size of the file. This is called from within L{_set_mode} + (subclass override) + Return the size of the file. This is called from within :class:`_set_mode` if the file is opened in append mode, so the file position can be - tracked and L{seek} and L{tell} will work correctly. If the file is + tracked and :class:`seek` and :class:`tell` will work correctly. If the file is a stream that can't be randomly accessed, you don't need to override this method, """ diff --git a/paramiko/hostkeys.py b/paramiko/hostkeys.py index f967a3da..a26e1fb2 100644 --- a/paramiko/hostkeys.py +++ b/paramiko/hostkeys.py @@ -17,7 +17,7 @@ # 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA. """ -L{HostKeys} +:class:`HostKeys` """ import base64 @@ -59,8 +59,8 @@ class HostKeyEntry: We don't bother to check for comments or empty lines. All of that should be taken care of before sending the line to us. - @param line: a line from an OpenSSH known_hosts file - @type line: str + :param line: a line from an OpenSSH known_hosts file + :type line: str """ log = get_logger('paramiko.hostkeys') fields = line.split(' ') @@ -112,9 +112,9 @@ class HostKeys (UserDict.DictMixin): verify server keys during SSH negotiation. A HostKeys object can be treated like a dict; any dict lookup is equivalent - to calling L{lookup}. + to calling :class:`lookup`. - @since: 1.5.3 + .. versionadded:: 1.5.3 """ def __init__(self, filename=None): @@ -122,8 +122,8 @@ class HostKeys (UserDict.DictMixin): Create a new HostKeys object, optionally loading keys from an openssh style host-key file. - @param filename: filename to load host keys from, or C{None} - @type filename: str + :param filename: filename to load host keys from, or ``None`` + :type filename: str """ # emulate a dict of { hostname: { keytype: PKey } } self._entries = [] @@ -133,14 +133,14 @@ class HostKeys (UserDict.DictMixin): def add(self, hostname, keytype, key): """ Add a host key entry to the table. Any existing entry for a - C{(hostname, keytype)} pair will be replaced. - - @param hostname: the hostname (or IP) to add - @type hostname: str - @param keytype: key type (C{"ssh-rsa"} or C{"ssh-dss"}) - @type keytype: str - @param key: the key to add - @type key: L{PKey} + ``(hostname, keytype)`` pair will be replaced. + + :param hostname: the hostname (or IP) to add + :type hostname: str + :param keytype: key type (``"ssh-rsa"`` or ``"ssh-dss"``) + :type keytype: str + :param key: the key to add + :type key: :class:`PKey` """ for e in self._entries: if (hostname in e.hostnames) and (e.key.get_name() == keytype): @@ -153,16 +153,16 @@ class HostKeys (UserDict.DictMixin): Read a file of known SSH host keys, in the format used by openssh. This type of file unfortunately doesn't exist on Windows, but on posix, it will usually be stored in - C{os.path.expanduser("~/.ssh/known_hosts")}. + ``os.path.expanduser("~/.ssh/known_hosts")``. If this method is called multiple times, the host keys are merged, - not cleared. So multiple calls to C{load} will just call L{add}, + not cleared. So multiple calls to ``load`` will just call :class:`add`, replacing any existing entries and adding new ones. - @param filename: name of the file to read host keys from - @type filename: str + :param filename: name of the file to read host keys from + :type filename: str - @raise IOError: if there was an error reading the file + :raises IOError: if there was an error reading the file """ f = open(filename, 'r') for lineno, line in enumerate(f): @@ -186,12 +186,12 @@ class HostKeys (UserDict.DictMixin): loaded from a file originally). The single exception is that combined lines will be split into individual key lines, which is arguably a bug. - @param filename: name of the file to write - @type filename: str + :param filename: name of the file to write + :type filename: str - @raise IOError: if there was an error writing the file + :raises IOError: if there was an error writing the file - @since: 1.6.1 + .. versionadded:: 1.6.1 """ f = open(filename, 'w') for e in self._entries: @@ -203,13 +203,13 @@ class HostKeys (UserDict.DictMixin): def lookup(self, hostname): """ Find a hostkey entry for a given hostname or IP. If no entry is found, - C{None} is returned. Otherwise a dictionary of keytype to key is - returned. The keytype will be either C{"ssh-rsa"} or C{"ssh-dss"}. + ``None`` is returned. Otherwise a dictionary of keytype to key is + returned. The keytype will be either ``"ssh-rsa"`` or ``"ssh-dss"``. - @param hostname: the hostname (or IP) to lookup - @type hostname: str - @return: keys associated with this host (or C{None}) - @rtype: dict(str, L{PKey}) + :param hostname: the hostname (or IP) to lookup + :type hostname: str + :return: keys associated with this host (or ``None``) + :rtype: dict(str, :class:`PKey`) """ class SubDict (UserDict.DictMixin): def __init__(self, hostname, entries, hostkeys): @@ -254,13 +254,13 @@ class HostKeys (UserDict.DictMixin): Return True if the given key is associated with the given hostname in this dictionary. - @param hostname: hostname (or IP) of the SSH server - @type hostname: str - @param key: the key to check - @type key: L{PKey} - @return: C{True} if the key is associated with the hostname; C{False} + :param hostname: hostname (or IP) of the SSH server + :type hostname: str + :param key: the key to check + :type key: :class:`PKey` + :return: ``True`` if the key is associated with the hostname; ``False`` if not - @rtype: bool + :rtype: bool """ k = self.lookup(hostname) if k is None: @@ -317,12 +317,12 @@ class HostKeys (UserDict.DictMixin): Return a "hashed" form of the hostname, as used by openssh when storing hashed hostnames in the known_hosts file. - @param hostname: the hostname to hash - @type hostname: str - @param salt: optional salt to use when hashing (must be 20 bytes long) - @type salt: str - @return: the hashed hostname - @rtype: str + :param hostname: the hostname to hash + :type hostname: str + :param salt: optional salt to use when hashing (must be 20 bytes long) + :type salt: str + :return: the hashed hostname + :rtype: str """ if salt is None: salt = rng.read(SHA.digest_size) diff --git a/paramiko/kex_gex.py b/paramiko/kex_gex.py index c0455a1f..c0b24453 100644 --- a/paramiko/kex_gex.py +++ b/paramiko/kex_gex.py @@ -17,7 +17,7 @@ # 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA. """ -Variant on L{KexGroup1 } where the prime "p" and +Variant on :class:`KexGroup1 ` where the prime "p" and generator "g" are provided by the server. A bit more work is required on the client side, and a B{lot} more on the server side. """ diff --git a/paramiko/message.py b/paramiko/message.py index c0e8692b..85fb3c09 100644 --- a/paramiko/message.py +++ b/paramiko/message.py @@ -28,9 +28,9 @@ from paramiko import util class Message (object): """ - An SSH2 I{Message} is a stream of bytes that encodes some combination of + An SSH2 Message is a stream of bytes that encodes some combination of strings, integers, bools, and infinite-precision integers (known in python - as I{long}s). This class builds or breaks down such a byte stream. + as longs). This class builds or breaks down such a byte stream. Normally you don't need to deal with anything this low-level, but it's exposed for people implementing custom extensions, or features that @@ -41,9 +41,9 @@ class Message (object): """ Create a new SSH2 Message. - @param content: the byte stream to use as the Message content (passed + :param content: the byte stream to use as the Message content (passed in only when decomposing a Message). - @type content: string + :type content: string """ if content != None: self.packet = cStringIO.StringIO(content) @@ -54,8 +54,8 @@ class Message (object): """ Return the byte stream content of this Message, as a string. - @return: the contents of this Message. - @rtype: string + :return: the contents of this Message. + :rtype: string """ return self.packet.getvalue() @@ -63,7 +63,7 @@ class Message (object): """ Returns a string representation of this object, for debugging. - @rtype: string + :rtype: string """ return 'paramiko.Message(' + repr(self.packet.getvalue()) + ')' @@ -79,8 +79,8 @@ class Message (object): Return the bytes of this Message that haven't already been parsed and returned. - @return: a string of the bytes not parsed yet. - @rtype: string + :return: a string of the bytes not parsed yet. + :rtype: string """ position = self.packet.tell() remainder = self.packet.read() @@ -91,10 +91,10 @@ class Message (object): """ Returns the bytes of this Message that have been parsed and returned. The string passed into a Message's constructor can be regenerated by - concatenating C{get_so_far} and L{get_remainder}. + concatenating ``get_so_far`` and :class:`get_remainder`. - @return: a string of the bytes parsed so far. - @rtype: string + :return: a string of the bytes parsed so far. + :rtype: string """ position = self.packet.tell() self.rewind() @@ -102,12 +102,12 @@ class Message (object): def get_bytes(self, n): """ - Return the next C{n} bytes of the Message, without decomposing into + Return the next ``n`` bytes of the Message, without decomposing into an int, string, etc. Just the raw bytes are returned. - @return: a string of the next C{n} bytes of the Message, or a string - of C{n} zero bytes, if there aren't C{n} bytes remaining. - @rtype: string + :return: a string of the next ``n`` bytes of the Message, or a string + of ``n`` zero bytes, if there aren't ``n`` bytes remaining. + :rtype: string """ b = self.packet.read(n) max_pad_size = 1<<20 # Limit padding to 1 MB @@ -118,11 +118,11 @@ class Message (object): def get_byte(self): """ Return the next byte of the Message, without decomposing it. This - is equivalent to L{get_bytes(1)}. + is equivalent to :class:`get_bytes(1)`. - @return: the next byte of the Message, or C{'\000'} if there aren't + :return: the next byte of the Message, or ``'\000'`` if there aren't any bytes remaining. - @rtype: string + :rtype: string """ return self.get_bytes(1) @@ -130,8 +130,8 @@ class Message (object): """ Fetch a boolean from the stream. - @return: C{True} or C{False} (from the Message). - @rtype: bool + :return: ``True`` or ``False`` (from the Message). + :rtype: bool """ b = self.get_bytes(1) return b != '\x00' @@ -140,8 +140,8 @@ class Message (object): """ Fetch an int from the stream. - @return: a 32-bit unsigned integer. - @rtype: int + :return: a 32-bit unsigned integer. + :rtype: int """ return struct.unpack('>I', self.get_bytes(4))[0] @@ -149,8 +149,8 @@ class Message (object): """ Fetch a 64-bit int from the stream. - @return: a 64-bit unsigned integer. - @rtype: long + :return: a 64-bit unsigned integer. + :rtype: long """ return struct.unpack('>Q', self.get_bytes(8))[0] @@ -158,8 +158,8 @@ class Message (object): """ Fetch a long int (mpint) from the stream. - @return: an arbitrary-length integer. - @rtype: long + :return: an arbitrary-length integer. + :rtype: long """ return util.inflate_long(self.get_string()) @@ -169,8 +169,8 @@ class Message (object): contain unprintable characters. (It's not unheard of for a string to contain another byte-stream Message.) - @return: a string. - @rtype: string + :return: a string. + :rtype: string """ return self.get_bytes(self.get_int()) @@ -179,8 +179,8 @@ class Message (object): Fetch a list of strings from the stream. These are trivially encoded as comma-separated values in a string. - @return: a list of strings. - @rtype: list of strings + :return: a list of strings. + :rtype: list of strings """ return self.get_string().split(',') @@ -188,8 +188,8 @@ class Message (object): """ Write bytes to the stream, without any formatting. - @param b: bytes to add - @type b: str + :param b: bytes to add + :type b: str """ self.packet.write(b) return self @@ -198,8 +198,8 @@ class Message (object): """ Write a single byte to the stream, without any formatting. - @param b: byte to add - @type b: str + :param b: byte to add + :type b: str """ self.packet.write(b) return self @@ -208,8 +208,8 @@ class Message (object): """ Add a boolean value to the stream. - @param b: boolean value to add - @type b: bool + :param b: boolean value to add + :type b: bool """ if b: self.add_byte('\x01') @@ -221,8 +221,8 @@ class Message (object): """ Add an integer to the stream. - @param n: integer to add - @type n: int + :param n: integer to add + :type n: int """ self.packet.write(struct.pack('>I', n)) return self @@ -231,8 +231,8 @@ class Message (object): """ Add a 64-bit int to the stream. - @param n: long int to add - @type n: long + :param n: long int to add + :type n: long """ self.packet.write(struct.pack('>Q', n)) return self @@ -242,8 +242,8 @@ class Message (object): Add a long int to the stream, encoded as an infinite-precision integer. This method only works on positive numbers. - @param z: long int to add - @type z: long + :param z: long int to add + :type z: long """ self.add_string(util.deflate_long(z)) return self @@ -252,8 +252,8 @@ class Message (object): """ Add a string to the stream. - @param s: string to add - @type s: str + :param s: string to add + :type s: str """ self.add_int(len(s)) self.packet.write(s) @@ -265,8 +265,8 @@ class Message (object): a single string of values separated by commas. (Yes, really, that's how SSH2 does it.) - @param l: list of strings to add - @type l: list(str) + :param l: list of strings to add + :type l: list(str) """ self.add_string(','.join(l)) return self @@ -293,8 +293,8 @@ class Message (object): Add a sequence of items to the stream. The values are encoded based on their type: str, int, bool, list, or long. - @param seq: the sequence of items - @type seq: sequence + :param seq: the sequence of items + :type seq: sequence @bug: longs are encoded non-deterministically. Don't use this method. """ diff --git a/paramiko/packet.py b/paramiko/packet.py index 3f85d668..90293d34 100644 --- a/paramiko/packet.py +++ b/paramiko/packet.py @@ -168,17 +168,17 @@ class Packetizer (object): def need_rekey(self): """ - Returns C{True} if a new set of keys needs to be negotiated. This + Returns ``True`` if a new set of keys needs to be negotiated. This will be triggered during a packet read or write, so it should be checked after every read or write, or at least after every few. - @return: C{True} if a new set of keys needs to be negotiated + :return: ``True`` if a new set of keys needs to be negotiated """ return self.__need_rekey def set_keepalive(self, interval, callback): """ - Turn on/off the callback keepalive. If C{interval} seconds pass with + Turn on/off the callback keepalive. If ``interval`` seconds pass with no data read from or written to the socket, the callback will be executed and the timer will be reset. """ @@ -190,11 +190,11 @@ class Packetizer (object): """ Read as close to N bytes as possible, blocking as long as necessary. - @param n: number of bytes to read - @type n: int - @return: the data read - @rtype: str - @raise EOFError: if the socket was closed before all the bytes could + :param n: number of bytes to read + :type n: int + :return: the data read + :rtype: str + :raises EOFError: if the socket was closed before all the bytes could be read """ out = '' @@ -332,8 +332,8 @@ class Packetizer (object): Only one thread should ever be in this function (no other locking is done). - @raise SSHException: if the packet is mangled - @raise NeedRekeyException: if the transport should rekey + :raises SSHException: if the packet is mangled + :raises NeedRekeyException: if the transport should rekey """ header = self.read_all(self.__block_size_in, check_rekey=True) if self.__block_engine_in != None: diff --git a/paramiko/pkey.py b/paramiko/pkey.py index b1199df8..bfe7b116 100644 --- a/paramiko/pkey.py +++ b/paramiko/pkey.py @@ -47,30 +47,30 @@ class PKey (object): def __init__(self, msg=None, data=None): """ - Create a new instance of this public key type. If C{msg} is given, + Create a new instance of this public key type. If ``msg`` is given, the key's public part(s) will be filled in from the message. If - C{data} is given, the key's public part(s) will be filled in from + ``data`` is given, the key's public part(s) will be filled in from the string. - @param msg: an optional SSH L{Message} containing a public key of this + :param msg: an optional SSH :class:`Message` containing a public key of this type. - @type msg: L{Message} - @param data: an optional string containing a public key of this type - @type data: str + :type msg: :class:`Message` + :param data: an optional string containing a public key of this type + :type data: str - @raise SSHException: if a key cannot be created from the C{data} or - C{msg} given, or no key was passed in. + :raises SSHException: if a key cannot be created from the ``data`` or + ``msg`` given, or no key was passed in. """ pass def __str__(self): """ - Return a string of an SSH L{Message} made up of the public part(s) of - this key. This string is suitable for passing to L{__init__} to + Return a string of an SSH :class:`Message` made up of the public part(s) of + this key. This string is suitable for passing to :class:`__init__` to re-create the key object later. - @return: string representation of an SSH key message. - @rtype: str + :return: string representation of an SSH key message. + :rtype: str """ return '' @@ -81,10 +81,10 @@ class PKey (object): of the key are compared, so a public key will compare equal to its corresponding private key. - @param other: key to compare to. - @type other: L{PKey} - @return: 0 if the two keys are equivalent, non-0 otherwise. - @rtype: int + :param other: key to compare to. + :type other: :class:`PKey` + :return: 0 if the two keys are equivalent, non-0 otherwise. + :rtype: int """ hs = hash(self) ho = hash(other) @@ -96,9 +96,9 @@ class PKey (object): """ Return the name of this private key implementation. - @return: name of this private key type, in SSH terminology (for - example, C{"ssh-rsa"}). - @rtype: str + :return: name of this private key type, in SSH terminology (for + example, ``"ssh-rsa"``). + :rtype: str """ return '' @@ -107,18 +107,18 @@ class PKey (object): Return the number of significant bits in this key. This is useful for judging the relative security of a key. - @return: bits in the key. - @rtype: int + :return: bits in the key. + :rtype: int """ return 0 def can_sign(self): """ - Return C{True} if this key has the private part necessary for signing + Return ``True`` if this key has the private part necessary for signing data. - @return: C{True} if this is a private key. - @rtype: bool + :return: ``True`` if this is a private key. + :rtype: bool """ return False @@ -127,9 +127,9 @@ class PKey (object): Return an MD5 fingerprint of the public part of this key. Nothing secret is revealed. - @return: a 16-byte string (binary) of the MD5 fingerprint, in SSH + :return: a 16-byte string (binary) of the MD5 fingerprint, in SSH format. - @rtype: str + :rtype: str """ return MD5.new(str(self)).digest() @@ -139,22 +139,22 @@ class PKey (object): secret is revealed. This format is compatible with that used to store public key files or recognized host keys. - @return: a base64 string containing the public part of the key. - @rtype: str + :return: a base64 string containing the public part of the key. + :rtype: str """ return base64.encodestring(str(self)).replace('\n', '') def sign_ssh_data(self, rng, data): """ - Sign a blob of data with this private key, and return a L{Message} + Sign a blob of data with this private key, and return a :class:`Message` representing an SSH signature message. - @param rng: a secure random number generator. - @type rng: L{Crypto.Util.rng.RandomPool} - @param data: the data to sign. - @type data: str - @return: an SSH signature message. - @rtype: L{Message} + :param rng: a secure random number generator. + :type rng: :class:`Crypto.Util.rng.RandomPool` + :param data: the data to sign. + :type data: str + :return: an SSH signature message. + :rtype: :class:`Message` """ return '' @@ -163,37 +163,37 @@ class PKey (object): Given a blob of data, and an SSH message representing a signature of that data, verify that it was signed with this key. - @param data: the data that was signed. - @type data: str - @param msg: an SSH signature message - @type msg: L{Message} - @return: C{True} if the signature verifies correctly; C{False} + :param data: the data that was signed. + :type data: str + :param msg: an SSH signature message + :type msg: :class:`Message` + :return: ``True`` if the signature verifies correctly; ``False`` otherwise. - @rtype: boolean + :rtype: boolean """ return False def from_private_key_file(cls, filename, password=None): """ Create a key object by reading a private key file. If the private - key is encrypted and C{password} is not C{None}, the given password - will be used to decrypt the key (otherwise L{PasswordRequiredException} + key is encrypted and ``password`` is not ``None``, the given password + will be used to decrypt the key (otherwise :class:`PasswordRequiredException` is thrown). Through the magic of python, this factory method will - exist in all subclasses of PKey (such as L{RSAKey} or L{DSSKey}), but + exist in all subclasses of PKey (such as :class:`RSAKey` or :class:`DSSKey`), but is useless on the abstract PKey class. - @param filename: name of the file to read - @type filename: str - @param password: an optional password to use to decrypt the key file, + :param filename: name of the file to read + :type filename: str + :param password: an optional password to use to decrypt the key file, if it's encrypted - @type password: str - @return: a new key object based on the given private key - @rtype: L{PKey} + :type password: str + :return: a new key object based on the given private key + :rtype: :class:`PKey` - @raise IOError: if there was an error reading the file - @raise PasswordRequiredException: if the private key file is - encrypted, and C{password} is C{None} - @raise SSHException: if the key file is invalid + :raises IOError: if there was an error reading the file + :raises PasswordRequiredException: if the private key file is + encrypted, and ``password`` is ``None`` + :raises SSHException: if the key file is invalid """ key = cls(filename=filename, password=password) return key @@ -202,22 +202,22 @@ class PKey (object): def from_private_key(cls, file_obj, password=None): """ Create a key object by reading a private key from a file (or file-like) - object. If the private key is encrypted and C{password} is not C{None}, + object. If the private key is encrypted and ``password`` is not ``None``, the given password will be used to decrypt the key (otherwise - L{PasswordRequiredException} is thrown). + :class:`PasswordRequiredException` is thrown). - @param file_obj: the file to read from - @type file_obj: file - @param password: an optional password to use to decrypt the key, if it's + :param file_obj: the file to read from + :type file_obj: file + :param password: an optional password to use to decrypt the key, if it's encrypted - @type password: str - @return: a new key object based on the given private key - @rtype: L{PKey} + :type password: str + :return: a new key object based on the given private key + :rtype: :class:`PKey` - @raise IOError: if there was an error reading the key - @raise PasswordRequiredException: if the private key file is encrypted, - and C{password} is C{None} - @raise SSHException: if the key file is invalid + :raises IOError: if there was an error reading the key + :raises PasswordRequiredException: if the private key file is encrypted, + and ``password`` is ``None`` + :raises SSHException: if the key file is invalid """ key = cls(file_obj=file_obj, password=password) return key @@ -226,55 +226,55 @@ class PKey (object): def write_private_key_file(self, filename, password=None): """ Write private key contents into a file. If the password is not - C{None}, the key is encrypted before writing. + ``None``, the key is encrypted before writing. - @param filename: name of the file to write - @type filename: str - @param password: an optional password to use to encrypt the key file - @type password: str + :param filename: name of the file to write + :type filename: str + :param password: an optional password to use to encrypt the key file + :type password: str - @raise IOError: if there was an error writing the file - @raise SSHException: if the key is invalid + :raises IOError: if there was an error writing the file + :raises SSHException: if the key is invalid """ raise Exception('Not implemented in PKey') def write_private_key(self, file_obj, password=None): """ Write private key contents into a file (or file-like) object. If the - password is not C{None}, the key is encrypted before writing. + password is not ``None``, the key is encrypted before writing. - @param file_obj: the file object to write into - @type file_obj: file - @param password: an optional password to use to encrypt the key - @type password: str + :param file_obj: the file object to write into + :type file_obj: file + :param password: an optional password to use to encrypt the key + :type password: str - @raise IOError: if there was an error writing to the file - @raise SSHException: if the key is invalid + :raises IOError: if there was an error writing to the file + :raises SSHException: if the key is invalid """ raise Exception('Not implemented in PKey') def _read_private_key_file(self, tag, filename, password=None): """ Read an SSH2-format private key file, looking for a string of the type - C{"BEGIN xxx PRIVATE KEY"} for some C{xxx}, base64-decode the text we + ``"BEGIN xxx PRIVATE KEY"`` for some ``xxx``, base64-decode the text we find, and return it as a string. If the private key is encrypted and - C{password} is not C{None}, the given password will be used to decrypt - the key (otherwise L{PasswordRequiredException} is thrown). - - @param tag: C{"RSA"} or C{"DSA"}, the tag used to mark the data block. - @type tag: str - @param filename: name of the file to read. - @type filename: str - @param password: an optional password to use to decrypt the key file, + ``password`` is not ``None``, the given password will be used to decrypt + the key (otherwise :class:`PasswordRequiredException` is thrown). + + :param tag: ``"RSA"`` or ``"DSA"``, the tag used to mark the data block. + :type tag: str + :param filename: name of the file to read. + :type filename: str + :param password: an optional password to use to decrypt the key file, if it's encrypted. - @type password: str - @return: data blob that makes up the private key. - @rtype: str + :type password: str + :return: data blob that makes up the private key. + :rtype: str - @raise IOError: if there was an error reading the file. - @raise PasswordRequiredException: if the private key file is - encrypted, and C{password} is C{None}. - @raise SSHException: if the key file is invalid. + :raises IOError: if there was an error reading the file. + :raises PasswordRequiredException: if the private key file is + encrypted, and ``password`` is ``None``. + :raises SSHException: if the key file is invalid. """ f = open(filename, 'r') data = self._read_private_key(tag, f, password) @@ -335,16 +335,16 @@ class PKey (object): a trivially-encoded format (base64) which is completely insecure. If a password is given, DES-EDE3-CBC is used. - @param tag: C{"RSA"} or C{"DSA"}, the tag used to mark the data block. - @type tag: str - @param filename: name of the file to write. - @type filename: str - @param data: data blob that makes up the private key. - @type data: str - @param password: an optional password to use to encrypt the file. - @type password: str + :param tag: ``"RSA"`` or ``"DSA"``, the tag used to mark the data block. + :type tag: str + :param filename: name of the file to write. + :type filename: str + :param data: data blob that makes up the private key. + :type data: str + :param password: an optional password to use to encrypt the file. + :type password: str - @raise IOError: if there was an error writing the file. + :raises IOError: if there was an error writing the file. """ f = open(filename, 'w', 0600) # grrr... the mode doesn't always take hold diff --git a/paramiko/primes.py b/paramiko/primes.py index 9419cd6b..86b9953a 100644 --- a/paramiko/primes.py +++ b/paramiko/primes.py @@ -109,7 +109,7 @@ class ModulusPack (object): def read_file(self, filename): """ - @raise IOError: passed from any file operations that fail. + :raises IOError: passed from any file operations that fail. """ self.pack = {} f = open(filename, 'r') diff --git a/paramiko/proxy.py b/paramiko/proxy.py index 218b76e2..08abe9a6 100644 --- a/paramiko/proxy.py +++ b/paramiko/proxy.py @@ -17,7 +17,7 @@ # 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA. """ -L{ProxyCommand}. +:class:`ProxyCommand`. """ import os @@ -33,18 +33,18 @@ class ProxyCommand(object): Wraps a subprocess running ProxyCommand-driven programs. This class implements a the socket-like interface needed by the - L{Transport} and L{Packetizer} classes. Using this class instead of a + :class:`Transport` and :class:`Packetizer` classes. Using this class instead of a regular socket makes it possible to talk with a Popen'd command that will proxy traffic between the client and a server hosted in another machine. """ def __init__(self, command_line): """ Create a new CommandProxy instance. The instance created by this - class can be passed as an argument to the L{Transport} class. + class can be passed as an argument to the :class:`Transport` class. - @param command_line: the command that should be executed and + :param command_line: the command that should be executed and used as the proxy. - @type command_line: str + :type command_line: str """ self.cmd = shlsplit(command_line) self.process = Popen(self.cmd, stdin=PIPE, stdout=PIPE, stderr=PIPE) @@ -54,8 +54,8 @@ class ProxyCommand(object): Write the content received from the SSH client to the standard input of the forked command. - @param content: string to be sent to the forked command - @type content: str + :param content: string to be sent to the forked command + :type content: str """ try: self.process.stdin.write(content) @@ -71,11 +71,11 @@ class ProxyCommand(object): """ Read from the standard output of the forked program. - @param size: how many chars should be read - @type size: int + :param size: how many chars should be read + :type size: int - @return: the length of the read content - @rtype: int + :return: the length of the read content + :rtype: int """ try: return os.read(self.process.stdout.fileno(), size) diff --git a/paramiko/resource.py b/paramiko/resource.py index 6ef86d8c..1d1f8da4 100644 --- a/paramiko/resource.py +++ b/paramiko/resource.py @@ -28,13 +28,13 @@ class ResourceManager (object): A registry of objects and resources that should be closed when those objects are deleted. - This is meant to be a safer alternative to python's C{__del__} method, + This is meant to be a safer alternative to python's ``__del__`` method, which can cause reference cycles to never be collected. Objects registered with the ResourceManager can be collected but still free resources when they die. - Resources are registered using L{register}, and when an object is garbage - collected, each registered resource is closed by having its C{close()} + Resources are registered using :class:`register`, and when an object is garbage + collected, each registered resource is closed by having its ``close()`` method called. Multiple resources may be registered per object, but a resource will only be closed once, even if multiple objects register it. (The last object to register it wins.) @@ -47,14 +47,14 @@ class ResourceManager (object): """ Register a resource to be closed with an object is collected. - When the given C{obj} is garbage-collected by the python interpreter, - the C{resource} will be closed by having its C{close()} method called. + When the given ``obj`` is garbage-collected by the python interpreter, + the ``resource`` will be closed by having its ``close()`` method called. Any exceptions are ignored. - @param obj: the object to track - @type obj: object - @param resource: the resource to close when the object is collected - @type resource: object + :param obj: the object to track + :type obj: object + :param resource: the resource to close when the object is collected + :type resource: object """ def callback(ref): try: diff --git a/paramiko/rsakey.py b/paramiko/rsakey.py index c7500f85..46c37d69 100644 --- a/paramiko/rsakey.py +++ b/paramiko/rsakey.py @@ -17,7 +17,7 @@ # 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA. """ -L{RSAKey} +:class:`RSAKey` """ from Crypto.PublicKey import RSA @@ -129,13 +129,13 @@ class RSAKey (PKey): Generate a new private RSA key. This factory function can be used to generate a new host key or authentication key. - @param bits: number of bits the generated key should be. - @type bits: int - @param progress_func: an optional function to call at key points in - key generation (used by C{pyCrypto.PublicKey}). - @type progress_func: function - @return: new private key - @rtype: L{RSAKey} + :param bits: number of bits the generated key should be. + :type bits: int + :param progress_func: an optional function to call at key points in + key generation (used by ``pyCrypto.PublicKey``). + :type progress_func: function + :return: new private key + :rtype: :class:`RSAKey` """ rsa = RSA.generate(bits, rng.read, progress_func) key = RSAKey(vals=(rsa.e, rsa.n)) diff --git a/paramiko/server.py b/paramiko/server.py index d737e056..380831ea 100644 --- a/paramiko/server.py +++ b/paramiko/server.py @@ -17,7 +17,7 @@ # 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA. """ -L{ServerInterface} is an interface to override for server support. +:class:`ServerInterface` is an interface to override for server support. """ import threading @@ -35,14 +35,14 @@ class InteractiveQuery (object): Create a new interactive query to send to the client. The name and instructions are optional, but are generally displayed to the end user. A list of prompts may be included, or they may be added via - the L{add_prompt} method. + the :class:`add_prompt` method. - @param name: name of this query - @type name: str - @param instructions: user instructions (usually short) about this query - @type instructions: str - @param prompts: one or more authentication prompts - @type prompts: str + :param name: name of this query + :type name: str + :param instructions: user instructions (usually short) about this query + :type instructions: str + :param prompts: one or more authentication prompts + :type prompts: str """ self.name = name self.instructions = instructions @@ -58,11 +58,11 @@ class InteractiveQuery (object): Add a prompt to this query. The prompt should be a (reasonably short) string. Multiple prompts can be added to the same query. - @param prompt: the user prompt - @type prompt: str - @param echo: C{True} (default) if the user's response should be echoed; - C{False} if not (for a password or similar) - @type echo: bool + :param prompt: the user prompt + :type prompt: str + :param echo: ``True`` (default) if the user's response should be echoed; + ``False`` if not (for a password or similar) + :type echo: bool """ self.prompts.append((prompt, echo)) @@ -80,7 +80,7 @@ class ServerInterface (object): def check_channel_request(self, kind, chanid): """ Determine if a channel request of a given type will be granted, and - return C{OPEN_SUCCEEDED} or an error code. This method is + return ``OPEN_SUCCEEDED`` or an error code. This method is called in server mode when the client requests a channel, after authentication is complete. @@ -88,37 +88,37 @@ class ServerInterface (object): useless), you should also override some of the channel request methods below, which are used to determine which services will be allowed on a given channel: - - L{check_channel_pty_request} - - L{check_channel_shell_request} - - L{check_channel_subsystem_request} - - L{check_channel_window_change_request} - - L{check_channel_x11_request} - - L{check_channel_forward_agent_request} - - The C{chanid} parameter is a small number that uniquely identifies the - channel within a L{Transport}. A L{Channel} object is not created - unless this method returns C{OPEN_SUCCEEDED} -- once a - L{Channel} object is created, you can call L{Channel.get_id} to + - :class:`check_channel_pty_request` + - :class:`check_channel_shell_request` + - :class:`check_channel_subsystem_request` + - :class:`check_channel_window_change_request` + - :class:`check_channel_x11_request` + - :class:`check_channel_forward_agent_request` + + The ``chanid`` parameter is a small number that uniquely identifies the + channel within a :class:`Transport`. A :class:`Channel` object is not created + unless this method returns ``OPEN_SUCCEEDED`` -- once a + :class:`Channel` object is created, you can call :class:`Channel.get_id` to retrieve the channel ID. - The return value should either be C{OPEN_SUCCEEDED} (or - C{0}) to allow the channel request, or one of the following error + The return value should either be ``OPEN_SUCCEEDED`` (or + ``0``) to allow the channel request, or one of the following error codes to reject it: - - C{OPEN_FAILED_ADMINISTRATIVELY_PROHIBITED} - - C{OPEN_FAILED_CONNECT_FAILED} - - C{OPEN_FAILED_UNKNOWN_CHANNEL_TYPE} - - C{OPEN_FAILED_RESOURCE_SHORTAGE} + - ``OPEN_FAILED_ADMINISTRATIVELY_PROHIBITED`` + - ``OPEN_FAILED_CONNECT_FAILED`` + - ``OPEN_FAILED_UNKNOWN_CHANNEL_TYPE`` + - ``OPEN_FAILED_RESOURCE_SHORTAGE`` The default implementation always returns - C{OPEN_FAILED_ADMINISTRATIVELY_PROHIBITED}. + ``OPEN_FAILED_ADMINISTRATIVELY_PROHIBITED``. - @param kind: the kind of channel the client would like to open - (usually C{"session"}). - @type kind: str - @param chanid: ID of the channel - @type chanid: int - @return: a success or failure code (listed above) - @rtype: int + :param kind: the kind of channel the client would like to open + (usually ``"session"``). + :type kind: str + :param chanid: ID of the channel + :type chanid: int + :return: a success or failure code (listed above) + :rtype: int """ return OPEN_FAILED_ADMINISTRATIVELY_PROHIBITED @@ -129,15 +129,15 @@ class ServerInterface (object): of authentication methods that might be successful. The "list" is actually a string of comma-separated names of types of - authentication. Possible values are C{"password"}, C{"publickey"}, - and C{"none"}. + authentication. Possible values are ``"password"``, ``"publickey"``, + and ``"none"``. - The default implementation always returns C{"password"}. + The default implementation always returns ``"password"``. - @param username: the username requesting authentication. - @type username: str - @return: a comma-separated list of authentication types - @rtype: str + :param username: the username requesting authentication. + :type username: str + :return: a comma-separated list of authentication types + :rtype: str """ return 'password' @@ -146,17 +146,17 @@ class ServerInterface (object): Determine if a client may open channels with no (further) authentication. - Return L{AUTH_FAILED} if the client must authenticate, or - L{AUTH_SUCCESSFUL} if it's okay for the client to not + Return :class:`AUTH_FAILED` if the client must authenticate, or + :class:`AUTH_SUCCESSFUL` if it's okay for the client to not authenticate. - The default implementation always returns L{AUTH_FAILED}. + The default implementation always returns :class:`AUTH_FAILED`. - @param username: the username of the client. - @type username: str - @return: L{AUTH_FAILED} if the authentication fails; - L{AUTH_SUCCESSFUL} if it succeeds. - @rtype: int + :param username: the username of the client. + :type username: str + :return: :class:`AUTH_FAILED` if the authentication fails; + :class:`AUTH_SUCCESSFUL` if it succeeds. + :rtype: int """ return AUTH_FAILED @@ -165,25 +165,25 @@ class ServerInterface (object): Determine if a given username and password supplied by the client is acceptable for use in authentication. - Return L{AUTH_FAILED} if the password is not accepted, - L{AUTH_SUCCESSFUL} if the password is accepted and completes - the authentication, or L{AUTH_PARTIALLY_SUCCESSFUL} if your + Return :class:`AUTH_FAILED` if the password is not accepted, + :class:`AUTH_SUCCESSFUL` if the password is accepted and completes + the authentication, or :class:`AUTH_PARTIALLY_SUCCESSFUL` if your authentication is stateful, and this key is accepted for authentication, but more authentication is required. (In this latter - case, L{get_allowed_auths} will be called to report to the client what + case, :class:`get_allowed_auths` will be called to report to the client what options it has for continuing the authentication.) - The default implementation always returns L{AUTH_FAILED}. + The default implementation always returns :class:`AUTH_FAILED`. - @param username: the username of the authenticating client. - @type username: str - @param password: the password given by the client. - @type password: str - @return: L{AUTH_FAILED} if the authentication fails; - L{AUTH_SUCCESSFUL} if it succeeds; - L{AUTH_PARTIALLY_SUCCESSFUL} if the password auth is + :param username: the username of the authenticating client. + :type username: str + :param password: the password given by the client. + :type password: str + :return: :class:`AUTH_FAILED` if the authentication fails; + :class:`AUTH_SUCCESSFUL` if it succeeds; + :class:`AUTH_PARTIALLY_SUCCESSFUL` if the password auth is successful, but authentication must continue. - @rtype: int + :rtype: int """ return AUTH_FAILED @@ -194,29 +194,29 @@ class ServerInterface (object): check the username and key and decide if you would accept a signature made using this key. - Return L{AUTH_FAILED} if the key is not accepted, - L{AUTH_SUCCESSFUL} if the key is accepted and completes the - authentication, or L{AUTH_PARTIALLY_SUCCESSFUL} if your + Return :class:`AUTH_FAILED` if the key is not accepted, + :class:`AUTH_SUCCESSFUL` if the key is accepted and completes the + authentication, or :class:`AUTH_PARTIALLY_SUCCESSFUL` if your authentication is stateful, and this password is accepted for authentication, but more authentication is required. (In this latter - case, L{get_allowed_auths} will be called to report to the client what + case, :class:`get_allowed_auths` will be called to report to the client what options it has for continuing the authentication.) Note that you don't have to actually verify any key signtature here. If you're willing to accept the key, paramiko will do the work of verifying the client's signature. - The default implementation always returns L{AUTH_FAILED}. - - @param username: the username of the authenticating client - @type username: str - @param key: the key object provided by the client - @type key: L{PKey } - @return: L{AUTH_FAILED} if the client can't authenticate - with this key; L{AUTH_SUCCESSFUL} if it can; - L{AUTH_PARTIALLY_SUCCESSFUL} if it can authenticate with + The default implementation always returns :class:`AUTH_FAILED`. + + :param username: the username of the authenticating client + :type username: str + :param key: the key object provided by the client + :type key: :class:`PKey ` + :return: :class:`AUTH_FAILED` if the client can't authenticate + with this key; :class:`AUTH_SUCCESSFUL` if it can; + :class:`AUTH_PARTIALLY_SUCCESSFUL` if it can authenticate with this key but must continue with authentication - @rtype: int + :rtype: int """ return AUTH_FAILED @@ -224,24 +224,24 @@ class ServerInterface (object): """ Begin an interactive authentication challenge, if supported. You should override this method in server mode if you want to support the - C{"keyboard-interactive"} auth type, which requires you to send a + ``"keyboard-interactive"`` auth type, which requires you to send a series of questions for the client to answer. - Return L{AUTH_FAILED} if this auth method isn't supported. Otherwise, - you should return an L{InteractiveQuery} object containing the prompts + Return :class:`AUTH_FAILED` if this auth method isn't supported. Otherwise, + you should return an :class:`InteractiveQuery` object containing the prompts and instructions for the user. The response will be sent via a call - to L{check_auth_interactive_response}. + to :class:`check_auth_interactive_response`. - The default implementation always returns L{AUTH_FAILED}. + The default implementation always returns :class:`AUTH_FAILED`. - @param username: the username of the authenticating client - @type username: str - @param submethods: a comma-separated list of methods preferred by the + :param username: the username of the authenticating client + :type username: str + :param submethods: a comma-separated list of methods preferred by the client (usually empty) - @type submethods: str - @return: L{AUTH_FAILED} if this auth method isn't supported; otherwise + :type submethods: str + :return: :class:`AUTH_FAILED` if this auth method isn't supported; otherwise an object containing queries for the user - @rtype: int or L{InteractiveQuery} + :rtype: int or :class:`InteractiveQuery` """ return AUTH_FAILED @@ -249,31 +249,31 @@ class ServerInterface (object): """ Continue or finish an interactive authentication challenge, if supported. You should override this method in server mode if you want - to support the C{"keyboard-interactive"} auth type. + to support the ``"keyboard-interactive"`` auth type. - Return L{AUTH_FAILED} if the responses are not accepted, - L{AUTH_SUCCESSFUL} if the responses are accepted and complete - the authentication, or L{AUTH_PARTIALLY_SUCCESSFUL} if your + Return :class:`AUTH_FAILED` if the responses are not accepted, + :class:`AUTH_SUCCESSFUL` if the responses are accepted and complete + the authentication, or :class:`AUTH_PARTIALLY_SUCCESSFUL` if your authentication is stateful, and this set of responses is accepted for authentication, but more authentication is required. (In this latter - case, L{get_allowed_auths} will be called to report to the client what + case, :class:`get_allowed_auths` will be called to report to the client what options it has for continuing the authentication.) If you wish to continue interactive authentication with more questions, - you may return an L{InteractiveQuery} object, which should cause the + you may return an :class:`InteractiveQuery` object, which should cause the client to respond with more answers, calling this method again. This cycle can continue indefinitely. - The default implementation always returns L{AUTH_FAILED}. + The default implementation always returns :class:`AUTH_FAILED`. - @param responses: list of responses from the client - @type responses: list(str) - @return: L{AUTH_FAILED} if the authentication fails; - L{AUTH_SUCCESSFUL} if it succeeds; - L{AUTH_PARTIALLY_SUCCESSFUL} if the interactive auth is + :param responses: list of responses from the client + :type responses: list(str) + :return: :class:`AUTH_FAILED` if the authentication fails; + :class:`AUTH_SUCCESSFUL` if it succeeds; + :class:`AUTH_PARTIALLY_SUCCESSFUL` if the interactive auth is successful, but authentication must continue; otherwise an object containing queries for the user - @rtype: int or L{InteractiveQuery} + :rtype: int or :class:`InteractiveQuery` """ return AUTH_FAILED @@ -281,22 +281,22 @@ class ServerInterface (object): """ Handle a request for port forwarding. The client is asking that connections to the given address and port be forwarded back across - this ssh connection. An address of C{"0.0.0.0"} indicates a global - address (any address associated with this server) and a port of C{0} + this ssh connection. An address of ``"0.0.0.0"`` indicates a global + address (any address associated with this server) and a port of ``0`` indicates that no specific port is requested (usually the OS will pick a port). - The default implementation always returns C{False}, rejecting the + The default implementation always returns ``False``, rejecting the port forwarding request. If the request is accepted, you should return the port opened for listening. - @param address: the requested address - @type address: str - @param port: the requested port - @type port: int - @return: the port number that was opened for listening, or C{False} to + :param address: the requested address + :type address: str + :param port: the requested port + :type port: int + :return: the port number that was opened for listening, or ``False`` to reject - @rtype: int + :rtype: int """ return False @@ -306,19 +306,19 @@ class ServerInterface (object): If the given address and port is being forwarded across this ssh connection, the port should be closed. - @param address: the forwarded address - @type address: str - @param port: the forwarded port - @type port: int + :param address: the forwarded address + :type address: str + :param port: the forwarded port + :type port: int """ pass def check_global_request(self, kind, msg): """ - Handle a global request of the given C{kind}. This method is called + Handle a global request of the given ``kind``. This method is called in server mode and client mode, whenever the remote host makes a global request. If there are any arguments to the request, they will be in - C{msg}. + ``msg``. There aren't any useful global requests defined, aside from port forwarding, so usually this type of request is an extension to the @@ -329,19 +329,19 @@ class ServerInterface (object): sent back with the successful result. (Note that the items in the tuple can only be strings, ints, longs, or bools.) - The default implementation always returns C{False}, indicating that it + The default implementation always returns ``False``, indicating that it does not support any global requests. - @note: Port forwarding requests are handled separately, in - L{check_port_forward_request}. + .. note:: Port forwarding requests are handled separately, in + :class:`check_port_forward_request`. - @param kind: the kind of global request being made. - @type kind: str - @param msg: any extra arguments to the request. - @type msg: L{Message} - @return: C{True} or a tuple of data if the request was granted; - C{False} otherwise. - @rtype: bool + :param kind: the kind of global request being made. + :type kind: str + :param msg: any extra arguments to the request. + :type msg: :class:`Message` + :return: ``True`` or a tuple of data if the request was granted; + ``False`` otherwise. + :rtype: bool """ return False @@ -355,89 +355,89 @@ class ServerInterface (object): Determine if a pseudo-terminal of the given dimensions (usually requested for shell access) can be provided on the given channel. - The default implementation always returns C{False}. - - @param channel: the L{Channel} the pty request arrived on. - @type channel: L{Channel} - @param term: type of terminal requested (for example, C{"vt100"}). - @type term: str - @param width: width of screen in characters. - @type width: int - @param height: height of screen in characters. - @type height: int - @param pixelwidth: width of screen in pixels, if known (may be C{0} if + The default implementation always returns ``False``. + + :param channel: the :class:`Channel` the pty request arrived on. + :type channel: :class:`Channel` + :param term: type of terminal requested (for example, ``"vt100"``). + :type term: str + :param width: width of screen in characters. + :type width: int + :param height: height of screen in characters. + :type height: int + :param pixelwidth: width of screen in pixels, if known (may be ``0`` if unknown). - @type pixelwidth: int - @param pixelheight: height of screen in pixels, if known (may be C{0} + :type pixelwidth: int + :param pixelheight: height of screen in pixels, if known (may be ``0`` if unknown). - @type pixelheight: int - @return: C{True} if the psuedo-terminal has been allocated; C{False} + :type pixelheight: int + :return: ``True`` if the psuedo-terminal has been allocated; ``False`` otherwise. - @rtype: bool + :rtype: bool """ return False def check_channel_shell_request(self, channel): """ Determine if a shell will be provided to the client on the given - channel. If this method returns C{True}, the channel should be + channel. If this method returns ``True``, the channel should be connected to the stdin/stdout of a shell (or something that acts like a shell). - The default implementation always returns C{False}. + The default implementation always returns ``False``. - @param channel: the L{Channel} the request arrived on. - @type channel: L{Channel} - @return: C{True} if this channel is now hooked up to a shell; C{False} + :param channel: the :class:`Channel` the request arrived on. + :type channel: :class:`Channel` + :return: ``True`` if this channel is now hooked up to a shell; ``False`` if a shell can't or won't be provided. - @rtype: bool + :rtype: bool """ return False def check_channel_exec_request(self, channel, command): """ Determine if a shell command will be executed for the client. If this - method returns C{True}, the channel should be connected to the stdin, + method returns ``True``, the channel should be connected to the stdin, stdout, and stderr of the shell command. - The default implementation always returns C{False}. + The default implementation always returns ``False``. - @param channel: the L{Channel} the request arrived on. - @type channel: L{Channel} - @param command: the command to execute. - @type command: str - @return: C{True} if this channel is now hooked up to the stdin, - stdout, and stderr of the executing command; C{False} if the + :param channel: the :class:`Channel` the request arrived on. + :type channel: :class:`Channel` + :param command: the command to execute. + :type command: str + :return: ``True`` if this channel is now hooked up to the stdin, + stdout, and stderr of the executing command; ``False`` if the command will not be executed. - @rtype: bool + :rtype: bool - @since: 1.1 + .. versionadded:: 1.1 """ return False def check_channel_subsystem_request(self, channel, name): """ Determine if a requested subsystem will be provided to the client on - the given channel. If this method returns C{True}, all future I/O + the given channel. If this method returns ``True``, all future I/O through this channel will be assumed to be connected to the requested - subsystem. An example of a subsystem is C{sftp}. + subsystem. An example of a subsystem is ``sftp``. The default implementation checks for a subsystem handler assigned via - L{Transport.set_subsystem_handler}. + :class:`Transport.set_subsystem_handler`. If one has been set, the handler is invoked and this method returns - C{True}. Otherwise it returns C{False}. + ``True``. Otherwise it returns ``False``. - @note: Because the default implementation uses the L{Transport} to + .. note:: Because the default implementation uses the :class:`Transport` to identify valid subsystems, you probably won't need to override this method. - @param channel: the L{Channel} the pty request arrived on. - @type channel: L{Channel} - @param name: name of the requested subsystem. - @type name: str - @return: C{True} if this channel is now hooked up to the requested - subsystem; C{False} if that subsystem can't or won't be provided. - @rtype: bool + :param channel: the :class:`Channel` the pty request arrived on. + :type channel: :class:`Channel` + :param name: name of the requested subsystem. + :type name: str + :return: ``True`` if this channel is now hooked up to the requested + subsystem; ``False`` if that subsystem can't or won't be provided. + :rtype: bool """ handler_class, larg, kwarg = channel.get_transport()._get_subsystem_handler(name) if handler_class is None: @@ -451,102 +451,102 @@ class ServerInterface (object): Determine if the pseudo-terminal on the given channel can be resized. This only makes sense if a pty was previously allocated on it. - The default implementation always returns C{False}. + The default implementation always returns ``False``. - @param channel: the L{Channel} the pty request arrived on. - @type channel: L{Channel} - @param width: width of screen in characters. - @type width: int - @param height: height of screen in characters. - @type height: int - @param pixelwidth: width of screen in pixels, if known (may be C{0} if + :param channel: the :class:`Channel` the pty request arrived on. + :type channel: :class:`Channel` + :param width: width of screen in characters. + :type width: int + :param height: height of screen in characters. + :type height: int + :param pixelwidth: width of screen in pixels, if known (may be ``0`` if unknown). - @type pixelwidth: int - @param pixelheight: height of screen in pixels, if known (may be C{0} + :type pixelwidth: int + :param pixelheight: height of screen in pixels, if known (may be ``0`` if unknown). - @type pixelheight: int - @return: C{True} if the terminal was resized; C{False} if not. - @rtype: bool + :type pixelheight: int + :return: ``True`` if the terminal was resized; ``False`` if not. + :rtype: bool """ return False def check_channel_x11_request(self, channel, single_connection, auth_protocol, auth_cookie, screen_number): """ Determine if the client will be provided with an X11 session. If this - method returns C{True}, X11 applications should be routed through new - SSH channels, using L{Transport.open_x11_channel}. + method returns ``True``, X11 applications should be routed through new + SSH channels, using :class:`Transport.open_x11_channel`. - The default implementation always returns C{False}. + The default implementation always returns ``False``. - @param channel: the L{Channel} the X11 request arrived on - @type channel: L{Channel} - @param single_connection: C{True} if only a single X11 channel should + :param channel: the :class:`Channel` the X11 request arrived on + :type channel: :class:`Channel` + :param single_connection: ``True`` if only a single X11 channel should be opened - @type single_connection: bool - @param auth_protocol: the protocol used for X11 authentication - @type auth_protocol: str - @param auth_cookie: the cookie used to authenticate to X11 - @type auth_cookie: str - @param screen_number: the number of the X11 screen to connect to - @type screen_number: int - @return: C{True} if the X11 session was opened; C{False} if not - @rtype: bool + :type single_connection: bool + :param auth_protocol: the protocol used for X11 authentication + :type auth_protocol: str + :param auth_cookie: the cookie used to authenticate to X11 + :type auth_cookie: str + :param screen_number: the number of the X11 screen to connect to + :type screen_number: int + :return: ``True`` if the X11 session was opened; ``False`` if not + :rtype: bool """ return False def check_channel_forward_agent_request(self, channel): """ Determine if the client will be provided with an forward agent session. - If this method returns C{True}, the server will allow SSH Agent + If this method returns ``True``, the server will allow SSH Agent forwarding. - The default implementation always returns C{False}. + The default implementation always returns ``False``. - @param channel: the L{Channel} the request arrived on - @type channel: L{Channel} - @return: C{True} if the AgentForward was loaded; C{False} if not - @rtype: bool + :param channel: the :class:`Channel` the request arrived on + :type channel: :class:`Channel` + :return: ``True`` if the AgentForward was loaded; ``False`` if not + :rtype: bool """ return False def check_channel_direct_tcpip_request(self, chanid, origin, destination): """ Determine if a local port forwarding channel will be granted, and - return C{OPEN_SUCCEEDED} or an error code. This method is + return ``OPEN_SUCCEEDED`` or an error code. This method is called in server mode when the client requests a channel, after authentication is complete. - The C{chanid} parameter is a small number that uniquely identifies the - channel within a L{Transport}. A L{Channel} object is not created - unless this method returns C{OPEN_SUCCEEDED} -- once a - L{Channel} object is created, you can call L{Channel.get_id} to + The ``chanid`` parameter is a small number that uniquely identifies the + channel within a :class:`Transport`. A :class:`Channel` object is not created + unless this method returns ``OPEN_SUCCEEDED`` -- once a + :class:`Channel` object is created, you can call :class:`Channel.get_id` to retrieve the channel ID. The origin and destination parameters are (ip_address, port) tuples that correspond to both ends of the TCP connection in the forwarding tunnel. - The return value should either be C{OPEN_SUCCEEDED} (or - C{0}) to allow the channel request, or one of the following error + The return value should either be ``OPEN_SUCCEEDED`` (or + ``0``) to allow the channel request, or one of the following error codes to reject it: - - C{OPEN_FAILED_ADMINISTRATIVELY_PROHIBITED} - - C{OPEN_FAILED_CONNECT_FAILED} - - C{OPEN_FAILED_UNKNOWN_CHANNEL_TYPE} - - C{OPEN_FAILED_RESOURCE_SHORTAGE} + - ``OPEN_FAILED_ADMINISTRATIVELY_PROHIBITED`` + - ``OPEN_FAILED_CONNECT_FAILED`` + - ``OPEN_FAILED_UNKNOWN_CHANNEL_TYPE`` + - ``OPEN_FAILED_RESOURCE_SHORTAGE`` The default implementation always returns - C{OPEN_FAILED_ADMINISTRATIVELY_PROHIBITED}. + ``OPEN_FAILED_ADMINISTRATIVELY_PROHIBITED``. - @param chanid: ID of the channel - @type chanid: int - @param origin: 2-tuple containing the IP address and port of the + :param chanid: ID of the channel + :type chanid: int + :param origin: 2-tuple containing the IP address and port of the originator (client side) - @type origin: tuple - @param destination: 2-tuple containing the IP address and port of the + :type origin: tuple + :param destination: 2-tuple containing the IP address and port of the destination (server side) - @type destination: tuple - @return: a success or failure code (listed above) - @rtype: int + :type destination: tuple + :return: a success or failure code (listed above) + :rtype: int """ return OPEN_FAILED_ADMINISTRATIVELY_PROHIBITED @@ -555,33 +555,33 @@ class SubsystemHandler (threading.Thread): """ Handler for a subsytem in server mode. If you create a subclass of this class and pass it to - L{Transport.set_subsystem_handler}, + :class:`Transport.set_subsystem_handler`, an object of this class will be created for each request for this subsystem. Each new object - will be executed within its own new thread by calling L{start_subsystem}. + will be executed within its own new thread by calling :class:`start_subsystem`. When that method completes, the channel is closed. - For example, if you made a subclass C{MP3Handler} and registered it as the - handler for subsystem C{"mp3"}, then whenever a client has successfully - authenticated and requests subsytem C{"mp3"}, an object of class - C{MP3Handler} will be created, and L{start_subsystem} will be called on + For example, if you made a subclass ``MP3Handler`` and registered it as the + handler for subsystem ``"mp3"``, then whenever a client has successfully + authenticated and requests subsytem ``"mp3"``, an object of class + ``MP3Handler`` will be created, and :class:`start_subsystem` will be called on it from a new thread. """ def __init__(self, channel, name, server): """ - Create a new handler for a channel. This is used by L{ServerInterface} + Create a new handler for a channel. This is used by :class:`ServerInterface` to start up a new handler when a channel requests this subsystem. You don't need to override this method, but if you do, be sure to pass the - C{channel} and C{name} parameters through to the original C{__init__} + ``channel`` and ``name`` parameters through to the original ``__init__`` method here. - @param channel: the channel associated with this subsystem request. - @type channel: L{Channel} - @param name: name of the requested subsystem. - @type name: str - @param server: the server object for the session that started this + :param channel: the channel associated with this subsystem request. + :type channel: :class:`Channel` + :param name: name of the requested subsystem. + :type name: str + :param server: the server object for the session that started this subsystem - @type server: L{ServerInterface} + :type server: :class:`ServerInterface` """ threading.Thread.__init__(self, target=self._run) self.__channel = channel @@ -591,10 +591,10 @@ class SubsystemHandler (threading.Thread): def get_server(self): """ - Return the L{ServerInterface} object associated with this channel and + Return the :class:`ServerInterface` object associated with this channel and subsystem. - @rtype: L{ServerInterface} + :rtype: :class:`ServerInterface` """ return self.__server @@ -619,22 +619,22 @@ class SubsystemHandler (threading.Thread): subsystem is finished, this method will return. After this method returns, the channel is closed. - The combination of C{transport} and C{channel} are unique; this handler - corresponds to exactly one L{Channel} on one L{Transport}. + The combination of ``transport`` and ``channel`` are unique; this handler + corresponds to exactly one :class:`Channel` on one :class:`Transport`. - @note: It is the responsibility of this method to exit if the - underlying L{Transport} is closed. This can be done by checking - L{Transport.is_active} or noticing an EOF - on the L{Channel}. If this method loops forever without checking + .. note:: It is the responsibility of this method to exit if the + underlying :class:`Transport` is closed. This can be done by checking + :class:`Transport.is_active` or noticing an EOF + on the :class:`Channel`. If this method loops forever without checking for this case, your python interpreter may refuse to exit because this thread will still be running. - @param name: name of the requested subsystem. - @type name: str - @param transport: the server-mode L{Transport}. - @type transport: L{Transport} - @param channel: the channel associated with this subsystem request. - @type channel: L{Channel} + :param name: name of the requested subsystem. + :type name: str + :param transport: the server-mode :class:`Transport`. + :type transport: :class:`Transport` + :param channel: the channel associated with this subsystem request. + :type channel: :class:`Channel` """ pass @@ -643,6 +643,6 @@ class SubsystemHandler (threading.Thread): Perform any cleanup at the end of a subsystem. The default implementation just closes the channel. - @since: 1.1 + .. versionadded:: 1.1 """ self.__channel.close() diff --git a/paramiko/sftp_attr.py b/paramiko/sftp_attr.py index b459b04b..267bc3ab 100644 --- a/paramiko/sftp_attr.py +++ b/paramiko/sftp_attr.py @@ -26,8 +26,8 @@ class SFTPAttributes (object): """ Representation of the attributes of a file (or proxied file) for SFTP in client or server mode. It attemps to mirror the object returned by - C{os.stat} as closely as possible, so it may have the following fields, - with the same meanings as those returned by an C{os.stat} object: + ``os.stat`` as closely as possible, so it may have the following fields, + with the same meanings as those returned by an ``os.stat`` object: - st_size - st_uid - st_gid @@ -36,8 +36,8 @@ class SFTPAttributes (object): - st_mtime Because SFTP allows flags to have other arbitrary named attributes, these - are stored in a dict named C{attr}. Occasionally, the filename is also - stored, in C{filename}. + are stored in a dict named ``attr``. Occasionally, the filename is also + stored, in ``filename``. """ FLAG_SIZE = 1 @@ -61,15 +61,15 @@ class SFTPAttributes (object): def from_stat(cls, obj, filename=None): """ - Create an SFTPAttributes object from an existing C{stat} object (an - object returned by C{os.stat}). - - @param obj: an object returned by C{os.stat} (or equivalent). - @type obj: object - @param filename: the filename associated with this file. - @type filename: str - @return: new L{SFTPAttributes} object with the same attribute fields. - @rtype: L{SFTPAttributes} + Create an SFTPAttributes object from an existing ``stat`` object (an + object returned by ``os.stat``). + + :param obj: an object returned by ``os.stat`` (or equivalent). + :type obj: object + :param filename: the filename associated with this file. + :type filename: str + :return: new :class:`SFTPAttributes` object with the same attribute fields. + :rtype: :class:`SFTPAttributes` """ attr = cls() attr.st_size = obj.st_size diff --git a/paramiko/sftp_client.py b/paramiko/sftp_client.py index d9215743..895ca49c 100644 --- a/paramiko/sftp_client.py +++ b/paramiko/sftp_client.py @@ -51,22 +51,22 @@ def _to_unicode(s): class SFTPClient (BaseSFTP): """ - SFTP client object. C{SFTPClient} is used to open an sftp session across - an open ssh L{Transport} and do remote file operations. + SFTP client object. ``SFTPClient`` is used to open an sftp session across + an open ssh :class:`Transport` and do remote file operations. """ def __init__(self, sock): """ - Create an SFTP client from an existing L{Channel}. The channel - should already have requested the C{"sftp"} subsystem. + Create an SFTP client from an existing :class:`Channel`. The channel + should already have requested the ``"sftp"`` subsystem. An alternate way to create an SFTP client context is by using - L{from_transport}. + :class:`from_transport`. - @param sock: an open L{Channel} using the C{"sftp"} subsystem - @type sock: L{Channel} + :param sock: an open :class:`Channel` using the ``"sftp"`` subsystem + :type sock: :class:`Channel` - @raise SSHException: if there's an exception while negotiating + :raises SSHException: if there's an exception while negotiating sftp """ BaseSFTP.__init__(self) @@ -91,13 +91,13 @@ class SFTPClient (BaseSFTP): def from_transport(cls, t): """ - Create an SFTP client channel from an open L{Transport}. + Create an SFTP client channel from an open :class:`Transport`. - @param t: an open L{Transport} which is already authenticated - @type t: L{Transport} - @return: a new L{SFTPClient} object, referring to an sftp session + :param t: an open :class:`Transport` which is already authenticated + :type t: :class:`Transport` + :return: a new :class:`SFTPClient` object, referring to an sftp session (channel) across the transport - @rtype: L{SFTPClient} + :rtype: :class:`SFTPClient` """ chan = t.open_session() if chan is None: @@ -117,56 +117,56 @@ class SFTPClient (BaseSFTP): """ Close the SFTP session and its underlying channel. - @since: 1.4 + .. versionadded:: 1.4 """ self._log(INFO, 'sftp session closed.') self.sock.close() def get_channel(self): """ - Return the underlying L{Channel} object for this SFTP session. This + Return the underlying :class:`Channel` object for this SFTP session. This might be useful for doing things like setting a timeout on the channel. - @return: the SSH channel - @rtype: L{Channel} + :return: the SSH channel + :rtype: :class:`Channel` - @since: 1.7.1 + .. versionadded:: 1.7.1 """ return self.sock def listdir(self, path='.'): """ - Return a list containing the names of the entries in the given C{path}. + Return a list containing the names of the entries in the given ``path``. The list is in arbitrary order. It does not include the special - entries C{'.'} and C{'..'} even if they are present in the folder. - This method is meant to mirror C{os.listdir} as closely as possible. - For a list of full L{SFTPAttributes} objects, see L{listdir_attr}. + entries ``'.'`` and ``'..'`` even if they are present in the folder. + This method is meant to mirror ``os.listdir`` as closely as possible. + For a list of full :class:`SFTPAttributes` objects, see :class:`listdir_attr`. - @param path: path to list (defaults to C{'.'}) - @type path: str - @return: list of filenames - @rtype: list of str + :param path: path to list (defaults to ``'.'``) + :type path: str + :return: list of filenames + :rtype: list of str """ return [f.filename for f in self.listdir_attr(path)] def listdir_attr(self, path='.'): """ - Return a list containing L{SFTPAttributes} objects corresponding to - files in the given C{path}. The list is in arbitrary order. It does - not include the special entries C{'.'} and C{'..'} even if they are + Return a list containing :class:`SFTPAttributes` objects corresponding to + files in the given ``path``. The list is in arbitrary order. It does + not include the special entries ``'.'`` and ``'..'`` even if they are present in the folder. - The returned L{SFTPAttributes} objects will each have an additional - field: C{longname}, which may contain a formatted string of the file's + The returned :class:`SFTPAttributes` objects will each have an additional + field: ``longname``, which may contain a formatted string of the file's attributes, in unix format. The content of this string will probably depend on the SFTP server implementation. - @param path: path to list (defaults to C{'.'}) - @type path: str - @return: list of attributes - @rtype: list of L{SFTPAttributes} + :param path: path to list (defaults to ``'.'``) + :type path: str + :return: list of attributes + :rtype: list of :class:`SFTPAttributes` - @since: 1.2 + .. versionadded:: 1.2 """ path = self._adjust_cwd(path) self._log(DEBUG, 'listdir(%r)' % path) @@ -196,37 +196,37 @@ class SFTPClient (BaseSFTP): def open(self, filename, mode='r', bufsize=-1): """ Open a file on the remote server. The arguments are the same as for - python's built-in C{file} (aka C{open}). A file-like object is + python's built-in ``file`` (aka ``open``). A file-like object is returned, which closely mimics the behavior of a normal python file object, including the ability to be used as a context manager. - The mode indicates how the file is to be opened: C{'r'} for reading, - C{'w'} for writing (truncating an existing file), C{'a'} for appending, - C{'r+'} for reading/writing, C{'w+'} for reading/writing (truncating an - existing file), C{'a+'} for reading/appending. The python C{'b'} flag - is ignored, since SSH treats all files as binary. The C{'U'} flag is + The mode indicates how the file is to be opened: ``'r'`` for reading, + ``'w'`` for writing (truncating an existing file), ``'a'`` for appending, + ``'r+'`` for reading/writing, ``'w+'`` for reading/writing (truncating an + existing file), ``'a+'`` for reading/appending. The python ``'b'`` flag + is ignored, since SSH treats all files as binary. The ``'U'`` flag is supported in a compatible way. - Since 1.5.2, an C{'x'} flag indicates that the operation should only + Since 1.5.2, an ``'x'`` flag indicates that the operation should only succeed if the file was created and did not previously exist. This has no direct mapping to python's file flags, but is commonly known as the - C{O_EXCL} flag in posix. + ``O_EXCL`` flag in posix. The file will be buffered in standard python style by default, but - can be altered with the C{bufsize} parameter. C{0} turns off - buffering, C{1} uses line buffering, and any number greater than 1 - (C{>1}) uses that specific buffer size. + can be altered with the ``bufsize`` parameter. ``0`` turns off + buffering, ``1`` uses line buffering, and any number greater than 1 + (``>1``) uses that specific buffer size. - @param filename: name of the file to open - @type filename: str - @param mode: mode (python-style) to open in - @type mode: str - @param bufsize: desired buffering (-1 = default buffer size) - @type bufsize: int - @return: a file object representing the open file - @rtype: SFTPFile + :param filename: name of the file to open + :type filename: str + :param mode: mode (python-style) to open in + :type mode: str + :param bufsize: desired buffering (-1 = default buffer size) + :type bufsize: int + :return: a file object representing the open file + :rtype: SFTPFile - @raise IOError: if the file could not be opened. + :raises IOError: if the file could not be opened. """ filename = self._adjust_cwd(filename) self._log(DEBUG, 'open(%r, %r)' % (filename, mode)) @@ -255,12 +255,12 @@ class SFTPClient (BaseSFTP): def remove(self, path): """ Remove the file at the given path. This only works on files; for - removing folders (directories), use L{rmdir}. + removing folders (directories), use :class:`rmdir`. - @param path: path (absolute or relative) of the file to remove - @type path: str + :param path: path (absolute or relative) of the file to remove + :type path: str - @raise IOError: if the path refers to a folder (directory) + :raises IOError: if the path refers to a folder (directory) """ path = self._adjust_cwd(path) self._log(DEBUG, 'remove(%r)' % path) @@ -270,14 +270,14 @@ class SFTPClient (BaseSFTP): def rename(self, oldpath, newpath): """ - Rename a file or folder from C{oldpath} to C{newpath}. + Rename a file or folder from ``oldpath`` to ``newpath``. - @param oldpath: existing name of the file or folder - @type oldpath: str - @param newpath: new name for the file or folder - @type newpath: str + :param oldpath: existing name of the file or folder + :type oldpath: str + :param newpath: new name for the file or folder + :type newpath: str - @raise IOError: if C{newpath} is a folder, or something else goes + :raises IOError: if ``newpath`` is a folder, or something else goes wrong """ oldpath = self._adjust_cwd(oldpath) @@ -287,14 +287,14 @@ class SFTPClient (BaseSFTP): def mkdir(self, path, mode=0777): """ - Create a folder (directory) named C{path} with numeric mode C{mode}. + Create a folder (directory) named ``path`` with numeric mode ``mode``. The default mode is 0777 (octal). On some systems, mode is ignored. Where it is used, the current umask value is first masked out. - @param path: name of the folder to create - @type path: str - @param mode: permissions (posix-style) for the newly-created folder - @type mode: int + :param path: name of the folder to create + :type path: str + :param mode: permissions (posix-style) for the newly-created folder + :type mode: int """ path = self._adjust_cwd(path) self._log(DEBUG, 'mkdir(%r, %r)' % (path, mode)) @@ -304,10 +304,10 @@ class SFTPClient (BaseSFTP): def rmdir(self, path): """ - Remove the folder named C{path}. + Remove the folder named ``path``. - @param path: name of the folder to remove - @type path: str + :param path: name of the folder to remove + :type path: str """ path = self._adjust_cwd(path) self._log(DEBUG, 'rmdir(%r)' % path) @@ -317,20 +317,20 @@ class SFTPClient (BaseSFTP): """ Retrieve information about a file on the remote system. The return value is an object whose attributes correspond to the attributes of - python's C{stat} structure as returned by C{os.stat}, except that it + python's ``stat`` structure as returned by ``os.stat``, except that it contains fewer fields. An SFTP server may return as much or as little info as it wants, so the results may vary from server to server. - Unlike a python C{stat} object, the result may not be accessed as a + Unlike a python ``stat`` object, the result may not be accessed as a tuple. This is mostly due to the author's slack factor. - The fields supported are: C{st_mode}, C{st_size}, C{st_uid}, C{st_gid}, - C{st_atime}, and C{st_mtime}. + The fields supported are: ``st_mode``, ``st_size``, ``st_uid``, ``st_gid``, + ``st_atime``, and ``st_mtime``. - @param path: the filename to stat - @type path: str - @return: an object containing attributes about the given file - @rtype: SFTPAttributes + :param path: the filename to stat + :type path: str + :return: an object containing attributes about the given file + :rtype: SFTPAttributes """ path = self._adjust_cwd(path) self._log(DEBUG, 'stat(%r)' % path) @@ -343,12 +343,12 @@ class SFTPClient (BaseSFTP): """ Retrieve information about a file on the remote system, without following symbolic links (shortcuts). This otherwise behaves exactly - the same as L{stat}. + the same as :class:`stat`. - @param path: the filename to stat - @type path: str - @return: an object containing attributes about the given file - @rtype: SFTPAttributes + :param path: the filename to stat + :type path: str + :return: an object containing attributes about the given file + :rtype: SFTPAttributes """ path = self._adjust_cwd(path) self._log(DEBUG, 'lstat(%r)' % path) @@ -359,13 +359,13 @@ class SFTPClient (BaseSFTP): def symlink(self, source, dest): """ - Create a symbolic link (shortcut) of the C{source} path at - C{destination}. + Create a symbolic link (shortcut) of the ``source`` path at + ``destination``. - @param source: path of the original file - @type source: str - @param dest: path of the newly created symlink - @type dest: str + :param source: path of the original file + :type source: str + :param dest: path of the newly created symlink + :type dest: str """ dest = self._adjust_cwd(dest) self._log(DEBUG, 'symlink(%r, %r)' % (source, dest)) @@ -376,13 +376,13 @@ class SFTPClient (BaseSFTP): def chmod(self, path, mode): """ Change the mode (permissions) of a file. The permissions are - unix-style and identical to those used by python's C{os.chmod} + unix-style and identical to those used by python's ``os.chmod`` function. - @param path: path of the file to change the permissions of - @type path: str - @param mode: new permissions - @type mode: int + :param path: path of the file to change the permissions of + :type path: str + :param mode: new permissions + :type mode: int """ path = self._adjust_cwd(path) self._log(DEBUG, 'chmod(%r, %r)' % (path, mode)) @@ -392,17 +392,17 @@ class SFTPClient (BaseSFTP): def chown(self, path, uid, gid): """ - Change the owner (C{uid}) and group (C{gid}) of a file. As with - python's C{os.chown} function, you must pass both arguments, so if you - only want to change one, use L{stat} first to retrieve the current + Change the owner (``uid``) and group (``gid``) of a file. As with + python's ``os.chown`` function, you must pass both arguments, so if you + only want to change one, use :class:`stat` first to retrieve the current owner and group. - @param path: path of the file to change the owner and group of - @type path: str - @param uid: new owner's uid - @type uid: int - @param gid: new group id - @type gid: int + :param path: path of the file to change the owner and group of + :type path: str + :param uid: new owner's uid + :type uid: int + :param gid: new group id + :type gid: int """ path = self._adjust_cwd(path) self._log(DEBUG, 'chown(%r, %r, %r)' % (path, uid, gid)) @@ -412,18 +412,18 @@ class SFTPClient (BaseSFTP): def utime(self, path, times): """ - Set the access and modified times of the file specified by C{path}. If - C{times} is C{None}, then the file's access and modified times are set - to the current time. Otherwise, C{times} must be a 2-tuple of numbers, - of the form C{(atime, mtime)}, which is used to set the access and + Set the access and modified times of the file specified by ``path``. If + ``times`` is ``None``, then the file's access and modified times are set + to the current time. Otherwise, ``times`` must be a 2-tuple of numbers, + of the form ``(atime, mtime)``, which is used to set the access and modified times, respectively. This bizarre API is mimicked from python for the sake of consistency -- I apologize. - @param path: path of the file to modify - @type path: str - @param times: C{None} or a tuple of (access time, modified time) in + :param path: path of the file to modify + :type path: str + :param times: ``None`` or a tuple of (access time, modified time) in standard internet epoch time (seconds since 01 January 1970 GMT) - @type times: tuple(int) + :type times: tuple(int) """ path = self._adjust_cwd(path) if times is None: @@ -435,14 +435,14 @@ class SFTPClient (BaseSFTP): def truncate(self, path, size): """ - Change the size of the file specified by C{path}. This usually extends - or shrinks the size of the file, just like the C{truncate()} method on + Change the size of the file specified by ``path``. This usually extends + or shrinks the size of the file, just like the ``truncate()`` method on python file objects. - @param path: path of the file to modify - @type path: str - @param size: the new size of the file - @type size: int or long + :param path: path of the file to modify + :type path: str + :param size: the new size of the file + :type size: int or long """ path = self._adjust_cwd(path) self._log(DEBUG, 'truncate(%r, %r)' % (path, size)) @@ -453,13 +453,13 @@ class SFTPClient (BaseSFTP): def readlink(self, path): """ Return the target of a symbolic link (shortcut). You can use - L{symlink} to create these. The result may be either an absolute or + :class:`symlink` to create these. The result may be either an absolute or relative pathname. - @param path: path of the symbolic link file - @type path: str - @return: target path - @rtype: str + :param path: path of the symbolic link file + :type path: str + :return: target path + :rtype: str """ path = self._adjust_cwd(path) self._log(DEBUG, 'readlink(%r)' % path) @@ -477,15 +477,15 @@ class SFTPClient (BaseSFTP): """ Return the normalized path (on the server) of a given path. This can be used to quickly resolve symbolic links or determine what the - server is considering to be the "current folder" (by passing C{'.'} - as C{path}). + server is considering to be the "current folder" (by passing ``'.'`` + as ``path``). - @param path: path to be normalized - @type path: str - @return: normalized form of the given path - @rtype: str + :param path: path to be normalized + :type path: str + :return: normalized form of the given path + :rtype: str - @raise IOError: if the path can't be resolved on the server + :raises IOError: if the path can't be resolved on the server """ path = self._adjust_cwd(path) self._log(DEBUG, 'normalize(%r)' % path) @@ -503,15 +503,15 @@ class SFTPClient (BaseSFTP): doesn't really have the concept of a current working directory, this is emulated by paramiko. Once you use this method to set a working directory, all operations on this SFTPClient object will be relative - to that path. You can pass in C{None} to stop using a current working + to that path. You can pass in ``None`` to stop using a current working directory. - @param path: new current working directory - @type path: str + :param path: new current working directory + :type path: str - @raise IOError: if the requested path doesn't exist on the server + :raises IOError: if the requested path doesn't exist on the server - @since: 1.4 + .. versionadded:: 1.4 """ if path is None: self._cwd = None @@ -523,43 +523,43 @@ class SFTPClient (BaseSFTP): def getcwd(self): """ Return the "current working directory" for this SFTP session, as - emulated by paramiko. If no directory has been set with L{chdir}, - this method will return C{None}. + emulated by paramiko. If no directory has been set with :class:`chdir`, + this method will return ``None``. - @return: the current working directory on the server, or C{None} - @rtype: str + :return: the current working directory on the server, or ``None`` + :rtype: str - @since: 1.4 + .. versionadded:: 1.4 """ return self._cwd def putfo(self, fl, remotepath, file_size=0, callback=None, confirm=True): """ - Copy the contents of an open file object (C{fl}) to the SFTP server as - C{remotepath}. Any exception raised by operations will be passed through. + Copy the contents of an open file object (``fl``) to the SFTP server as + ``remotepath``. Any exception raised by operations will be passed through. The SFTP operations use pipelining for speed. - @param fl: opened file or file-like object to copy - @type localpath: object - @param remotepath: the destination path on the SFTP server - @type remotepath: str - @param file_size: optional size parameter passed to callback. If none is + :param fl: opened file or file-like object to copy + :type localpath: object + :param remotepath: the destination path on the SFTP server + :type remotepath: str + :param file_size: optional size parameter passed to callback. If none is specified, size defaults to 0 - @type file_size: int - @param callback: optional callback function that accepts the bytes + :type file_size: int + :param callback: optional callback function that accepts the bytes transferred so far and the total bytes to be transferred (since 1.7.4) - @type callback: function(int, int) - @param confirm: whether to do a stat() on the file afterwards to + :type callback: function(int, int) + :param confirm: whether to do a stat() on the file afterwards to confirm the file size (since 1.7.7) - @type confirm: bool + :type confirm: bool - @return: an object containing attributes about the given file + :return: an object containing attributes about the given file (since 1.7.4) - @rtype: SFTPAttributes + :rtype: SFTPAttributes - @since: 1.4 + .. versionadded:: 1.4 """ fr = self.file(remotepath, 'wb') fr.set_pipelined(True) @@ -585,29 +585,29 @@ class SFTPClient (BaseSFTP): def put(self, localpath, remotepath, callback=None, confirm=True): """ - Copy a local file (C{localpath}) to the SFTP server as C{remotepath}. + Copy a local file (``localpath``) to the SFTP server as ``remotepath``. Any exception raised by operations will be passed through. This method is primarily provided as a convenience. The SFTP operations use pipelining for speed. - @param localpath: the local file to copy - @type localpath: str - @param remotepath: the destination path on the SFTP server - @type remotepath: str - @param callback: optional callback function that accepts the bytes + :param localpath: the local file to copy + :type localpath: str + :param remotepath: the destination path on the SFTP server + :type remotepath: str + :param callback: optional callback function that accepts the bytes transferred so far and the total bytes to be transferred (since 1.7.4) - @type callback: function(int, int) - @param confirm: whether to do a stat() on the file afterwards to + :type callback: function(int, int) + :param confirm: whether to do a stat() on the file afterwards to confirm the file size (since 1.7.7) - @type confirm: bool + :type confirm: bool - @return: an object containing attributes about the given file + :return: an object containing attributes about the given file (since 1.7.4) - @rtype: SFTPAttributes + :rtype: SFTPAttributes - @since: 1.4 + .. versionadded:: 1.4 """ file_size = os.stat(localpath).st_size fl = file(localpath, 'rb') @@ -618,23 +618,23 @@ class SFTPClient (BaseSFTP): def getfo(self, remotepath, fl, callback=None): """ - Copy a remote file (C{remotepath}) from the SFTP server and write to - an open file or file-like object, C{fl}. Any exception raised by + Copy a remote file (``remotepath``) from the SFTP server and write to + an open file or file-like object, ``fl``. Any exception raised by operations will be passed through. This method is primarily provided as a convenience. - @param remotepath: opened file or file-like object to copy to - @type remotepath: object - @param fl: the destination path on the local host or open file + :param remotepath: opened file or file-like object to copy to + :type remotepath: object + :param fl: the destination path on the local host or open file object - @type localpath: str - @param callback: optional callback function that accepts the bytes + :type localpath: str + :param callback: optional callback function that accepts the bytes transferred so far and the total bytes to be transferred (since 1.7.4) - @type callback: function(int, int) - @return: the number of bytes written to the opened file object + :type callback: function(int, int) + :return: the number of bytes written to the opened file object - @since: 1.4 + .. versionadded:: 1.4 """ fr = self.file(remotepath, 'rb') file_size = self.stat(remotepath).st_size @@ -655,20 +655,20 @@ class SFTPClient (BaseSFTP): def get(self, remotepath, localpath, callback=None): """ - Copy a remote file (C{remotepath}) from the SFTP server to the local - host as C{localpath}. Any exception raised by operations will be + Copy a remote file (``remotepath``) from the SFTP server to the local + host as ``localpath``. Any exception raised by operations will be passed through. This method is primarily provided as a convenience. - @param remotepath: the remote file to copy - @type remotepath: str - @param localpath: the destination path on the local host - @type localpath: str - @param callback: optional callback function that accepts the bytes + :param remotepath: the remote file to copy + :type remotepath: str + :param localpath: the destination path on the local host + :type localpath: str + :param callback: optional callback function that accepts the bytes transferred so far and the total bytes to be transferred (since 1.7.4) - @type callback: function(int, int) + :type callback: function(int, int) - @since: 1.4 + .. versionadded:: 1.4 """ file_size = self.stat(remotepath).st_size fl = file(localpath, 'wb') @@ -783,5 +783,5 @@ class SFTPClient (BaseSFTP): class SFTP (SFTPClient): - "an alias for L{SFTPClient} for backwards compatability" + "an alias for :class:`SFTPClient` for backwards compatability" pass diff --git a/paramiko/sftp_file.py b/paramiko/sftp_file.py index 4ec936d0..fd82ae60 100644 --- a/paramiko/sftp_file.py +++ b/paramiko/sftp_file.py @@ -17,7 +17,7 @@ # 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA. """ -L{SFTPFile} +:class:`SFTPFile` """ from binascii import hexlify @@ -178,34 +178,34 @@ class SFTPFile (BufferedFile): def settimeout(self, timeout): """ Set a timeout on read/write operations on the underlying socket or - ssh L{Channel}. + ssh :class:`Channel`. - @see: L{Channel.settimeout} - @param timeout: seconds to wait for a pending read/write operation - before raising C{socket.timeout}, or C{None} for no timeout - @type timeout: float + .. seealso:: :class:`Channel.settimeout` + :param timeout: seconds to wait for a pending read/write operation + before raising ``socket.timeout``, or ``None`` for no timeout + :type timeout: float """ self.sftp.sock.settimeout(timeout) def gettimeout(self): """ Returns the timeout in seconds (as a float) associated with the socket - or ssh L{Channel} used for this file. + or ssh :class:`Channel` used for this file. - @see: L{Channel.gettimeout} - @rtype: float + .. seealso:: :class:`Channel.gettimeout` + :rtype: float """ return self.sftp.sock.gettimeout() def setblocking(self, blocking): """ Set blocking or non-blocking mode on the underiying socket or ssh - L{Channel}. + :class:`Channel`. - @see: L{Channel.setblocking} - @param blocking: 0 to set non-blocking mode; non-0 to set blocking + .. seealso:: :class:`Channel.setblocking` + :param blocking: 0 to set non-blocking mode; non-0 to set blocking mode. - @type blocking: int + :type blocking: int """ self.sftp.sock.setblocking(blocking) @@ -223,11 +223,11 @@ class SFTPFile (BufferedFile): def stat(self): """ Retrieve information about this file from the remote system. This is - exactly like L{SFTP.stat}, except that it operates on an already-open + exactly like :class:`SFTP.stat`, except that it operates on an already-open file. - @return: an object containing attributes about this file. - @rtype: SFTPAttributes + :return: an object containing attributes about this file. + :rtype: SFTPAttributes """ t, msg = self.sftp._request(CMD_FSTAT, self.handle) if t != CMD_ATTRS: @@ -237,11 +237,11 @@ class SFTPFile (BufferedFile): def chmod(self, mode): """ Change the mode (permissions) of this file. The permissions are - unix-style and identical to those used by python's C{os.chmod} + unix-style and identical to those used by python's ``os.chmod`` function. - @param mode: new permissions - @type mode: int + :param mode: new permissions + :type mode: int """ self.sftp._log(DEBUG, 'chmod(%s, %r)' % (hexlify(self.handle), mode)) attr = SFTPAttributes() @@ -250,15 +250,15 @@ class SFTPFile (BufferedFile): def chown(self, uid, gid): """ - Change the owner (C{uid}) and group (C{gid}) of this file. As with - python's C{os.chown} function, you must pass both arguments, so if you - only want to change one, use L{stat} first to retrieve the current + Change the owner (``uid``) and group (``gid``) of this file. As with + python's ``os.chown`` function, you must pass both arguments, so if you + only want to change one, use :class:`stat` first to retrieve the current owner and group. - @param uid: new owner's uid - @type uid: int - @param gid: new group id - @type gid: int + :param uid: new owner's uid + :type uid: int + :param gid: new group id + :type gid: int """ self.sftp._log(DEBUG, 'chown(%s, %r, %r)' % (hexlify(self.handle), uid, gid)) attr = SFTPAttributes() @@ -268,15 +268,15 @@ class SFTPFile (BufferedFile): def utime(self, times): """ Set the access and modified times of this file. If - C{times} is C{None}, then the file's access and modified times are set - to the current time. Otherwise, C{times} must be a 2-tuple of numbers, - of the form C{(atime, mtime)}, which is used to set the access and + ``times`` is ``None``, then the file's access and modified times are set + to the current time. Otherwise, ``times`` must be a 2-tuple of numbers, + of the form ``(atime, mtime)``, which is used to set the access and modified times, respectively. This bizarre API is mimicked from python for the sake of consistency -- I apologize. - @param times: C{None} or a tuple of (access time, modified time) in + :param times: ``None`` or a tuple of (access time, modified time) in standard internet epoch time (seconds since 01 January 1970 GMT) - @type times: tuple(int) + :type times: tuple(int) """ if times is None: times = (time.time(), time.time()) @@ -288,11 +288,11 @@ class SFTPFile (BufferedFile): def truncate(self, size): """ Change the size of this file. This usually extends - or shrinks the size of the file, just like the C{truncate()} method on + or shrinks the size of the file, just like the ``truncate()`` method on python file objects. - @param size: the new size of the file - @type size: int or long + :param size: the new size of the file + :type size: int or long """ self.sftp._log(DEBUG, 'truncate(%s, %r)' % (hexlify(self.handle), size)) attr = SFTPAttributes() @@ -305,46 +305,46 @@ class SFTPFile (BufferedFile): to verify a successful upload or download, or for various rsync-like operations. - The file is hashed from C{offset}, for C{length} bytes. If C{length} - is 0, the remainder of the file is hashed. Thus, if both C{offset} - and C{length} are zero, the entire file is hashed. + The file is hashed from ``offset``, for ``length`` bytes. If ``length`` + is 0, the remainder of the file is hashed. Thus, if both ``offset`` + and ``length`` are zero, the entire file is hashed. - Normally, C{block_size} will be 0 (the default), and this method will + Normally, ``block_size`` will be 0 (the default), and this method will return a byte string representing the requested hash (for example, a string of length 16 for MD5, or 20 for SHA-1). If a non-zero - C{block_size} is given, each chunk of the file (from C{offset} to - C{offset + length}) of C{block_size} bytes is computed as a separate + ``block_size`` is given, each chunk of the file (from ``offset`` to + ``offset + length``) of ``block_size`` bytes is computed as a separate hash. The hash results are all concatenated and returned as a single string. - For example, C{check('sha1', 0, 1024, 512)} will return a string of + For example, ``check('sha1', 0, 1024, 512)`` will return a string of length 40. The first 20 bytes will be the SHA-1 of the first 512 bytes of the file, and the last 20 bytes will be the SHA-1 of the next 512 bytes. - @param hash_algorithm: the name of the hash algorithm to use (normally - C{"sha1"} or C{"md5"}) - @type hash_algorithm: str - @param offset: offset into the file to begin hashing (0 means to start + :param hash_algorithm: the name of the hash algorithm to use (normally + ``"sha1"`` or ``"md5"``) + :type hash_algorithm: str + :param offset: offset into the file to begin hashing (0 means to start from the beginning) - @type offset: int or long - @param length: number of bytes to hash (0 means continue to the end of + :type offset: int or long + :param length: number of bytes to hash (0 means continue to the end of the file) - @type length: int or long - @param block_size: number of bytes to hash per result (must not be less + :type length: int or long + :param block_size: number of bytes to hash per result (must not be less than 256; 0 means to compute only one hash of the entire segment) - @type block_size: int - @return: string of bytes representing the hash of each block, + :type block_size: int + :return: string of bytes representing the hash of each block, concatenated together - @rtype: str + :rtype: str - @note: Many (most?) servers don't support this extension yet. + .. note:: Many (most?) servers don't support this extension yet. - @raise IOError: if the server doesn't support the "check-file" + :raises IOError: if the server doesn't support the "check-file" extension, or possibly doesn't support the hash algorithm requested - @since: 1.4 + .. versionadded:: 1.4 """ t, msg = self.sftp._request(CMD_EXTENDED, 'check-file', self.handle, hash_algorithm, long(offset), long(length), block_size) @@ -358,34 +358,34 @@ class SFTPFile (BufferedFile): Turn on/off the pipelining of write operations to this file. When pipelining is on, paramiko won't wait for the server response after each write operation. Instead, they're collected as they come in. - At the first non-write operation (including L{close}), all remaining + At the first non-write operation (including :class:`close`), all remaining server responses are collected. This means that if there was an error with one of your later writes, an exception might be thrown from - within L{close} instead of L{write}. + within :class:`close` instead of :class:`write`. - By default, files are I{not} pipelined. + By default, files are not pipelined. - @param pipelined: C{True} if pipelining should be turned on for this - file; C{False} otherwise - @type pipelined: bool + :param pipelined: ``True`` if pipelining should be turned on for this + file; ``False`` otherwise + :type pipelined: bool - @since: 1.5 + .. versionadded:: 1.5 """ self.pipelined = pipelined def prefetch(self): """ Pre-fetch the remaining contents of this file in anticipation of - future L{read} calls. If reading the entire file, pre-fetching can + future :class:`read` calls. If reading the entire file, pre-fetching can dramatically improve the download speed by avoiding roundtrip latency. The file's contents are incrementally buffered in a background thread. - The prefetched data is stored in a buffer until read via the L{read} + The prefetched data is stored in a buffer until read via the :class:`read` method. Once data has been read, it's removed from the buffer. The - data may be read in a random order (using L{seek}); chunks of the + data may be read in a random order (using :class:`seek`); chunks of the buffer that haven't been read will continue to be buffered. - @since: 1.5.1 + .. versionadded:: 1.5.1 """ size = self.stat().st_size # queue up async reads for the rest of the file @@ -401,17 +401,17 @@ class SFTPFile (BufferedFile): def readv(self, chunks): """ Read a set of blocks from the file by (offset, length). This is more - efficient than doing a series of L{seek} and L{read} calls, since the + efficient than doing a series of :class:`seek` and :class:`read` calls, since the prefetch machinery is used to retrieve all the requested blocks at once. - @param chunks: a list of (offset, length) tuples indicating which + :param chunks: a list of (offset, length) tuples indicating which sections of the file to read - @type chunks: list(tuple(long, int)) - @return: a list of blocks read, in the same order as in C{chunks} - @rtype: list(str) + :type chunks: list(tuple(long, int)) + :return: a list of blocks read, in the same order as in ``chunks`` + :rtype: list(str) - @since: 1.5.4 + .. versionadded:: 1.5.4 """ self.sftp._log(DEBUG, 'readv(%s, %r)' % (hexlify(self.handle), chunks)) diff --git a/paramiko/sftp_handle.py b/paramiko/sftp_handle.py index 29d3d0d8..c591b318 100644 --- a/paramiko/sftp_handle.py +++ b/paramiko/sftp_handle.py @@ -33,16 +33,16 @@ class SFTPHandle (object): by the client to refer to the underlying file. Server implementations can (and should) subclass SFTPHandle to implement - features of a file handle, like L{stat} or L{chattr}. + features of a file handle, like :class:`stat` or :class:`chattr`. """ def __init__(self, flags=0): """ Create a new file handle representing a local file being served over - SFTP. If C{flags} is passed in, it's used to determine if the file + SFTP. If ``flags`` is passed in, it's used to determine if the file is open in append mode. - @param flags: optional flags as passed to L{SFTPServerInterface.open} - @type flags: int + :param flags: optional flags as passed to :class:`SFTPServerInterface.open` + :type flags: int """ self.__flags = flags self.__name = None @@ -56,10 +56,10 @@ class SFTPHandle (object): Normally you would use this method to close the underlying OS level file object(s). - The default implementation checks for attributes on C{self} named - C{readfile} and/or C{writefile}, and if either or both are present, - their C{close()} methods are called. This means that if you are - using the default implementations of L{read} and L{write}, this + The default implementation checks for attributes on ``self`` named + ``readfile`` and/or ``writefile``, and if either or both are present, + their ``close()`` methods are called. This means that if you are + using the default implementations of :class:`read` and :class:`write`, this method's default implementation should be fine also. """ readfile = getattr(self, 'readfile', None) @@ -71,24 +71,24 @@ class SFTPHandle (object): def read(self, offset, length): """ - Read up to C{length} bytes from this file, starting at position - C{offset}. The offset may be a python long, since SFTP allows it + Read up to ``length`` bytes from this file, starting at position + ``offset``. The offset may be a python long, since SFTP allows it to be 64 bits. If the end of the file has been reached, this method may return an - empty string to signify EOF, or it may also return L{SFTP_EOF}. + empty string to signify EOF, or it may also return :class:`SFTP_EOF`. - The default implementation checks for an attribute on C{self} named - C{readfile}, and if present, performs the read operation on the python + The default implementation checks for an attribute on ``self`` named + ``readfile``, and if present, performs the read operation on the python file-like object found there. (This is meant as a time saver for the common case where you are wrapping a python file object.) - @param offset: position in the file to start reading from. - @type offset: int or long - @param length: number of bytes to attempt to read. - @type length: int - @return: data read from the file, or an SFTP error code. - @rtype: str + :param offset: position in the file to start reading from. + :type offset: int or long + :param length: number of bytes to attempt to read. + :type length: int + :return: data read from the file, or an SFTP error code. + :rtype: str """ readfile = getattr(self, 'readfile', None) if readfile is None: @@ -108,23 +108,23 @@ class SFTPHandle (object): def write(self, offset, data): """ - Write C{data} into this file at position C{offset}. Extending the + Write ``data`` into this file at position ``offset``. Extending the file past its original end is expected. Unlike python's normal - C{write()} methods, this method cannot do a partial write: it must - write all of C{data} or else return an error. + ``write()`` methods, this method cannot do a partial write: it must + write all of ``data`` or else return an error. - The default implementation checks for an attribute on C{self} named - C{writefile}, and if present, performs the write operation on the + The default implementation checks for an attribute on ``self`` named + ``writefile``, and if present, performs the write operation on the python file-like object found there. The attribute is named - differently from C{readfile} to make it easy to implement read-only + differently from ``readfile`` to make it easy to implement read-only (or write-only) files, but if both attributes are present, they should refer to the same file. - @param offset: position in the file to start reading from. - @type offset: int or long - @param data: data to write into the file. - @type data: str - @return: an SFTP error code like L{SFTP_OK}. + :param offset: position in the file to start reading from. + :type offset: int or long + :param data: data to write into the file. + :type data: str + :return: an SFTP error code like :class:`SFTP_OK`. """ writefile = getattr(self, 'writefile', None) if writefile is None: @@ -148,26 +148,26 @@ class SFTPHandle (object): def stat(self): """ - Return an L{SFTPAttributes} object referring to this open file, or an - error code. This is equivalent to L{SFTPServerInterface.stat}, except + Return an :class:`SFTPAttributes` object referring to this open file, or an + error code. This is equivalent to :class:`SFTPServerInterface.stat`, except it's called on an open file instead of a path. - @return: an attributes object for the given file, or an SFTP error - code (like L{SFTP_PERMISSION_DENIED}). - @rtype: L{SFTPAttributes} I{or error code} + :return: an attributes object for the given file, or an SFTP error + code (like :class:`SFTP_PERMISSION_DENIED`). + :rtype: :class:`SFTPAttributes` or error code """ return SFTP_OP_UNSUPPORTED def chattr(self, attr): """ - Change the attributes of this file. The C{attr} object will contain + Change the attributes of this file. The ``attr`` object will contain only those fields provided by the client in its request, so you should check for the presence of fields before using them. - @param attr: the attributes to change on this file. - @type attr: L{SFTPAttributes} - @return: an error code like L{SFTP_OK}. - @rtype: int + :param attr: the attributes to change on this file. + :type attr: :class:`SFTPAttributes` + :return: an error code like :class:`SFTP_OK`. + :rtype: int """ return SFTP_OP_UNSUPPORTED diff --git a/paramiko/sftp_server.py b/paramiko/sftp_server.py index 1833c2e8..867acbcb 100644 --- a/paramiko/sftp_server.py +++ b/paramiko/sftp_server.py @@ -40,28 +40,28 @@ _hash_class = { class SFTPServer (BaseSFTP, SubsystemHandler): """ - Server-side SFTP subsystem support. Since this is a L{SubsystemHandler}, - it can be (and is meant to be) set as the handler for C{"sftp"} requests. - Use L{Transport.set_subsystem_handler} to activate this class. + Server-side SFTP subsystem support. Since this is a :class:`SubsystemHandler`, + it can be (and is meant to be) set as the handler for ``"sftp"`` requests. + Use :class:`Transport.set_subsystem_handler` to activate this class. """ def __init__(self, channel, name, server, sftp_si=SFTPServerInterface, *largs, **kwargs): """ The constructor for SFTPServer is meant to be called from within the - L{Transport} as a subsystem handler. C{server} and any additional + :class:`Transport` as a subsystem handler. ``server`` and any additional parameters or keyword parameters are passed from the original call to - L{Transport.set_subsystem_handler}. + :class:`Transport.set_subsystem_handler`. - @param channel: channel passed from the L{Transport}. - @type channel: L{Channel} - @param name: name of the requested subsystem. - @type name: str - @param server: the server object associated with this channel and + :param channel: channel passed from the :class:`Transport`. + :type channel: :class:`Channel` + :param name: name of the requested subsystem. + :type name: str + :param server: the server object associated with this channel and subsystem - @type server: L{ServerInterface} - @param sftp_si: a subclass of L{SFTPServerInterface} to use for handling + :type server: :class:`ServerInterface` + :param sftp_si: a subclass of :class:`SFTPServerInterface` to use for handling individual requests. - @type sftp_si: class + :type sftp_si: class """ BaseSFTP.__init__(self) SubsystemHandler.__init__(self, channel, name, server) @@ -122,14 +122,14 @@ class SFTPServer (BaseSFTP, SubsystemHandler): def convert_errno(e): """ - Convert an errno value (as from an C{OSError} or C{IOError}) into a + Convert an errno value (as from an ``OSError`` or ``IOError``) into a standard SFTP result code. This is a convenience function for trapping exceptions in server code and returning an appropriate result. - @param e: an errno code, as from C{OSError.errno}. - @type e: int - @return: an SFTP error code like L{SFTP_NO_SUCH_FILE}. - @rtype: int + :param e: an errno code, as from ``OSError.errno``. + :type e: int + :return: an SFTP error code like :class:`SFTP_NO_SUCH_FILE`. + :rtype: int """ if e == errno.EACCES: # permission denied @@ -144,18 +144,18 @@ class SFTPServer (BaseSFTP, SubsystemHandler): def set_file_attr(filename, attr): """ Change a file's attributes on the local filesystem. The contents of - C{attr} are used to change the permissions, owner, group ownership, + ``attr`` are used to change the permissions, owner, group ownership, and/or modification & access time of the file, depending on which - attributes are present in C{attr}. + attributes are present in ``attr``. This is meant to be a handy helper function for translating SFTP file requests into local file operations. - @param filename: name of the file to alter (should usually be an + :param filename: name of the file to alter (should usually be an absolute path). - @type filename: str - @param attr: attributes to change. - @type attr: L{SFTPAttributes} + :type filename: str + :param attr: attributes to change. + :type attr: :class:`SFTPAttributes` """ if sys.platform != 'win32': # mode operations are meaningless on win32 diff --git a/paramiko/sftp_si.py b/paramiko/sftp_si.py index b0ee3c42..b203aea0 100644 --- a/paramiko/sftp_si.py +++ b/paramiko/sftp_si.py @@ -17,7 +17,7 @@ # 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA. """ -L{SFTPServerInterface} is an interface to override for SFTP server support. +:class:`SFTPServerInterface` is an interface to override for SFTP server support. """ import os @@ -29,7 +29,7 @@ from paramiko.sftp import * class SFTPServerInterface (object): """ This class defines an interface for controlling the behavior of paramiko - when using the L{SFTPServer} subsystem to provide an SFTP server. + when using the :class:`SFTPServer` subsystem to provide an SFTP server. Methods on this class are called from the SFTP session's thread, so you can block as long as necessary without affecting other sessions (even other @@ -46,9 +46,9 @@ class SFTPServerInterface (object): Create a new SFTPServerInterface object. This method does nothing by default and is meant to be overridden by subclasses. - @param server: the server object associated with this channel and + :param server: the server object associated with this channel and SFTP subsystem - @type server: L{ServerInterface} + :type server: :class:`ServerInterface` """ super(SFTPServerInterface, self).__init__(*largs, **kwargs) @@ -64,7 +64,7 @@ class SFTPServerInterface (object): """ The SFTP server session has just ended, either cleanly or via an exception. This method is meant to be overridden to perform any - necessary cleanup before this C{SFTPServerInterface} object is + necessary cleanup before this ``SFTPServerInterface`` object is destroyed. """ pass @@ -72,67 +72,67 @@ class SFTPServerInterface (object): def open(self, path, flags, attr): """ Open a file on the server and create a handle for future operations - on that file. On success, a new object subclassed from L{SFTPHandle} + on that file. On success, a new object subclassed from :class:`SFTPHandle` should be returned. This handle will be used for future operations on the file (read, write, etc). On failure, an error code such as - L{SFTP_PERMISSION_DENIED} should be returned. - - C{flags} contains the requested mode for opening (read-only, - write-append, etc) as a bitset of flags from the C{os} module: - - C{os.O_RDONLY} - - C{os.O_WRONLY} - - C{os.O_RDWR} - - C{os.O_APPEND} - - C{os.O_CREAT} - - C{os.O_TRUNC} - - C{os.O_EXCL} - (One of C{os.O_RDONLY}, C{os.O_WRONLY}, or C{os.O_RDWR} will always + :class:`SFTP_PERMISSION_DENIED` should be returned. + + ``flags`` contains the requested mode for opening (read-only, + write-append, etc) as a bitset of flags from the ``os`` module: + - ``os.O_RDONLY`` + - ``os.O_WRONLY`` + - ``os.O_RDWR`` + - ``os.O_APPEND`` + - ``os.O_CREAT`` + - ``os.O_TRUNC`` + - ``os.O_EXCL`` + (One of ``os.O_RDONLY``, ``os.O_WRONLY``, or ``os.O_RDWR`` will always be set.) - The C{attr} object contains requested attributes of the file if it + The ``attr`` object contains requested attributes of the file if it has to be created. Some or all attribute fields may be missing if the client didn't specify them. - @note: The SFTP protocol defines all files to be in "binary" mode. + .. note:: The SFTP protocol defines all files to be in "binary" mode. There is no equivalent to python's "text" mode. - @param path: the requested path (relative or absolute) of the file + :param path: the requested path (relative or absolute) of the file to be opened. - @type path: str - @param flags: flags or'd together from the C{os} module indicating the + :type path: str + :param flags: flags or'd together from the ``os`` module indicating the requested mode for opening the file. - @type flags: int - @param attr: requested attributes of the file if it is newly created. - @type attr: L{SFTPAttributes} - @return: a new L{SFTPHandle} I{or error code}. - @rtype L{SFTPHandle} + :type flags: int + :param attr: requested attributes of the file if it is newly created. + :type attr: :class:`SFTPAttributes` + :return: a new :class:`SFTPHandle` or error code. + :rtype :class:`SFTPHandle` """ return SFTP_OP_UNSUPPORTED def list_folder(self, path): """ - Return a list of files within a given folder. The C{path} will use - posix notation (C{"/"} separates folder names) and may be an absolute + Return a list of files within a given folder. The ``path`` will use + posix notation (``"/"`` separates folder names) and may be an absolute or relative path. - The list of files is expected to be a list of L{SFTPAttributes} + The list of files is expected to be a list of :class:`SFTPAttributes` objects, which are similar in structure to the objects returned by - C{os.stat}. In addition, each object should have its C{filename} + ``os.stat``. In addition, each object should have its ``filename`` field filled in, since this is important to a directory listing and - not normally present in C{os.stat} results. The method - L{SFTPAttributes.from_stat} will usually do what you want. + not normally present in ``os.stat`` results. The method + :class:`SFTPAttributes.from_stat` will usually do what you want. - In case of an error, you should return one of the C{SFTP_*} error - codes, such as L{SFTP_PERMISSION_DENIED}. + In case of an error, you should return one of the ``SFTP_*`` error + codes, such as :class:`SFTP_PERMISSION_DENIED`. - @param path: the requested path (relative or absolute) to be listed. - @type path: str - @return: a list of the files in the given folder, using - L{SFTPAttributes} objects. - @rtype: list of L{SFTPAttributes} I{or error code} + :param path: the requested path (relative or absolute) to be listed. + :type path: str + :return: a list of the files in the given folder, using + :class:`SFTPAttributes` objects. + :rtype: list of :class:`SFTPAttributes` or error code - @note: You should normalize the given C{path} first (see the - C{os.path} module) and check appropriate permissions before returning + .. note:: You should normalize the given ``path`` first (see the + ``os.path`` module) and check appropriate permissions before returning the list of files. Be careful of malicious clients attempting to use relative paths to escape restricted folders, if you're doing a direct translation from the SFTP server path to your local filesystem. @@ -141,34 +141,34 @@ class SFTPServerInterface (object): def stat(self, path): """ - Return an L{SFTPAttributes} object for a path on the server, or an + Return an :class:`SFTPAttributes` object for a path on the server, or an error code. If your server supports symbolic links (also known as - "aliases"), you should follow them. (L{lstat} is the corresponding + "aliases"), you should follow them. (:class:`lstat` is the corresponding call that doesn't follow symlinks/aliases.) - @param path: the requested path (relative or absolute) to fetch + :param path: the requested path (relative or absolute) to fetch file statistics for. - @type path: str - @return: an attributes object for the given file, or an SFTP error - code (like L{SFTP_PERMISSION_DENIED}). - @rtype: L{SFTPAttributes} I{or error code} + :type path: str + :return: an attributes object for the given file, or an SFTP error + code (like :class:`SFTP_PERMISSION_DENIED`). + :rtype: :class:`SFTPAttributes` or error code """ return SFTP_OP_UNSUPPORTED def lstat(self, path): """ - Return an L{SFTPAttributes} object for a path on the server, or an + Return an :class:`SFTPAttributes` object for a path on the server, or an error code. If your server supports symbolic links (also known as - "aliases"), you should I{not} follow them -- instead, you should - return data on the symlink or alias itself. (L{stat} is the + "aliases"), you should not follow them -- instead, you should + return data on the symlink or alias itself. (:class:`stat` is the corresponding call that follows symlinks/aliases.) - @param path: the requested path (relative or absolute) to fetch + :param path: the requested path (relative or absolute) to fetch file statistics for. - @type path: str - @return: an attributes object for the given file, or an SFTP error - code (like L{SFTP_PERMISSION_DENIED}). - @rtype: L{SFTPAttributes} I{or error code} + :type path: str + :return: an attributes object for the given file, or an SFTP error + code (like :class:`SFTP_PERMISSION_DENIED`). + :rtype: :class:`SFTPAttributes` or error code """ return SFTP_OP_UNSUPPORTED @@ -176,11 +176,11 @@ class SFTPServerInterface (object): """ Delete a file, if possible. - @param path: the requested path (relative or absolute) of the file + :param path: the requested path (relative or absolute) of the file to delete. - @type path: str - @return: an SFTP error code like L{SFTP_OK}. - @rtype: int + :type path: str + :return: an SFTP error code like :class:`SFTP_OK`. + :rtype: int """ return SFTP_OP_UNSUPPORTED @@ -192,83 +192,83 @@ class SFTPServerInterface (object): probably a good idea to implement "move" in this method too, even for files that cross disk partition boundaries, if at all possible. - @note: You should return an error if a file with the same name as - C{newpath} already exists. (The rename operation should be + .. note:: You should return an error if a file with the same name as + ``newpath`` already exists. (The rename operation should be non-desctructive.) - @param oldpath: the requested path (relative or absolute) of the + :param oldpath: the requested path (relative or absolute) of the existing file. - @type oldpath: str - @param newpath: the requested new path of the file. - @type newpath: str - @return: an SFTP error code like L{SFTP_OK}. - @rtype: int + :type oldpath: str + :param newpath: the requested new path of the file. + :type newpath: str + :return: an SFTP error code like :class:`SFTP_OK`. + :rtype: int """ return SFTP_OP_UNSUPPORTED def mkdir(self, path, attr): """ - Create a new directory with the given attributes. The C{attr} + Create a new directory with the given attributes. The ``attr`` object may be considered a "hint" and ignored. - The C{attr} object will contain only those fields provided by the - client in its request, so you should use C{hasattr} to check for - the presense of fields before using them. In some cases, the C{attr} + The ``attr`` object will contain only those fields provided by the + client in its request, so you should use ``hasattr`` to check for + the presense of fields before using them. In some cases, the ``attr`` object may be completely empty. - @param path: requested path (relative or absolute) of the new + :param path: requested path (relative or absolute) of the new folder. - @type path: str - @param attr: requested attributes of the new folder. - @type attr: L{SFTPAttributes} - @return: an SFTP error code like L{SFTP_OK}. - @rtype: int + :type path: str + :param attr: requested attributes of the new folder. + :type attr: :class:`SFTPAttributes` + :return: an SFTP error code like :class:`SFTP_OK`. + :rtype: int """ return SFTP_OP_UNSUPPORTED def rmdir(self, path): """ - Remove a directory if it exists. The C{path} should refer to an + Remove a directory if it exists. The ``path`` should refer to an existing, empty folder -- otherwise this method should return an error. - @param path: requested path (relative or absolute) of the folder + :param path: requested path (relative or absolute) of the folder to remove. - @type path: str - @return: an SFTP error code like L{SFTP_OK}. - @rtype: int + :type path: str + :return: an SFTP error code like :class:`SFTP_OK`. + :rtype: int """ return SFTP_OP_UNSUPPORTED def chattr(self, path, attr): """ - Change the attributes of a file. The C{attr} object will contain + Change the attributes of a file. The ``attr`` object will contain only those fields provided by the client in its request, so you should check for the presence of fields before using them. - @param path: requested path (relative or absolute) of the file to + :param path: requested path (relative or absolute) of the file to change. - @type path: str - @param attr: requested attributes to change on the file. - @type attr: L{SFTPAttributes} - @return: an error code like L{SFTP_OK}. - @rtype: int + :type path: str + :param attr: requested attributes to change on the file. + :type attr: :class:`SFTPAttributes` + :return: an error code like :class:`SFTP_OK`. + :rtype: int """ return SFTP_OP_UNSUPPORTED def canonicalize(self, path): """ Return the canonical form of a path on the server. For example, - if the server's home folder is C{/home/foo}, the path - C{"../betty"} would be canonicalized to C{"/home/betty"}. Note + if the server's home folder is ``/home/foo``, the path + ``"../betty"`` would be canonicalized to ``"/home/betty"``. Note the obvious security issues: if you're serving files only from a specific folder, you probably don't want this method to reveal path names outside that folder. - You may find the python methods in C{os.path} useful, especially - C{os.path.normpath} and C{os.path.realpath}. + You may find the python methods in ``os.path`` useful, especially + ``os.path.normpath`` and ``os.path.realpath``. - The default implementation returns C{os.path.normpath('/' + path)}. + The default implementation returns ``os.path.normpath('/' + path)``. """ if os.path.isabs(path): out = os.path.normpath(path) @@ -285,26 +285,26 @@ class SFTPServerInterface (object): If the specified path doesn't refer to a symbolic link, an error should be returned. - @param path: path (relative or absolute) of the symbolic link. - @type path: str - @return: the target path of the symbolic link, or an error code like - L{SFTP_NO_SUCH_FILE}. - @rtype: str I{or error code} + :param path: path (relative or absolute) of the symbolic link. + :type path: str + :return: the target path of the symbolic link, or an error code like + :class:`SFTP_NO_SUCH_FILE`. + :rtype: str or error code """ return SFTP_OP_UNSUPPORTED def symlink(self, target_path, path): """ - Create a symbolic link on the server, as new pathname C{path}, - with C{target_path} as the target of the link. + Create a symbolic link on the server, as new pathname ``path``, + with ``target_path`` as the target of the link. - @param target_path: path (relative or absolute) of the target for + :param target_path: path (relative or absolute) of the target for this new symbolic link. - @type target_path: str - @param path: path (relative or absolute) of the symbolic link to + :type target_path: str + :param path: path (relative or absolute) of the symbolic link to create. - @type path: str - @return: an error code like C{SFTP_OK}. - @rtype: int + :type path: str + :return: an error code like ``SFTP_OK``. + :rtype: int """ return SFTP_OP_UNSUPPORTED diff --git a/paramiko/ssh_exception.py b/paramiko/ssh_exception.py index b502b563..5b9b4901 100644 --- a/paramiko/ssh_exception.py +++ b/paramiko/ssh_exception.py @@ -34,7 +34,7 @@ class AuthenticationException (SSHException): possible to retry with different credentials. (Other classes specify more specific reasons.) - @since: 1.6 + .. versionadded:: 1.6 """ pass @@ -52,12 +52,12 @@ class BadAuthenticationType (AuthenticationException): the server isn't allowing that type. (It may only allow public-key, for example.) - @ivar allowed_types: list of allowed authentication types provided by the - server (possible values are: C{"none"}, C{"password"}, and - C{"publickey"}). - @type allowed_types: list + :ivar allowed_types: list of allowed authentication types provided by the + server (possible values are: ``"none"``, ``"password"``, and + ``"publickey"``). + :type allowed_types: list - @since: 1.1 + .. versionadded:: 1.1 """ allowed_types = [] @@ -82,12 +82,12 @@ class PartialAuthentication (AuthenticationException): class ChannelException (SSHException): """ - Exception raised when an attempt to open a new L{Channel} fails. + Exception raised when an attempt to open a new :class:`Channel` fails. - @ivar code: the error code returned by the server - @type code: int + :ivar code: the error code returned by the server + :type code: int - @since: 1.6 + .. versionadded:: 1.6 """ def __init__(self, code, text): SSHException.__init__(self, text) @@ -98,14 +98,14 @@ class BadHostKeyException (SSHException): """ The host key given by the SSH server did not match what we were expecting. - @ivar hostname: the hostname of the SSH server - @type hostname: str - @ivar key: the host key presented by the server - @type key: L{PKey} - @ivar expected_key: the host key expected - @type expected_key: L{PKey} + :ivar hostname: the hostname of the SSH server + :type hostname: str + :ivar key: the host key presented by the server + :type key: :class:`PKey` + :ivar expected_key: the host key expected + :type expected_key: :class:`PKey` - @since: 1.6 + .. versionadded:: 1.6 """ def __init__(self, hostname, got_key, expected_key): SSHException.__init__(self, 'Host key for server %s does not match!' % hostname) @@ -118,10 +118,10 @@ class ProxyCommandFailure (SSHException): """ The "ProxyCommand" found in the .ssh/config file returned an error. - @ivar command: The command line that is generating this exception. - @type command: str - @ivar error: The error captured from the proxy command output. - @type error: str + :ivar command: The command line that is generating this exception. + :type command: str + :ivar error: The error captured from the proxy command output. + :type error: str """ def __init__(self, command, error): SSHException.__init__(self, diff --git a/paramiko/transport.py b/paramiko/transport.py index 6c42cc27..7cccd5ff 100644 --- a/paramiko/transport.py +++ b/paramiko/transport.py @@ -17,7 +17,7 @@ # 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA. """ -L{Transport} handles the core SSH2 protocol. +:class:`Transport` handles the core SSH2 protocol. """ import os @@ -73,10 +73,10 @@ class SecurityOptions (object): exchange algorithms, listed in order of preference. Changing the contents and/or order of these fields affects the underlying - L{Transport} (but only if you change them before starting the session). + :class:`Transport` (but only if you change them before starting the session). If you try to add an algorithm that paramiko doesn't recognize, - C{ValueError} will be raised. If you try to assign something besides a - tuple to one of the fields, C{TypeError} will be raised. + ``ValueError`` will be raised. If you try to assign something besides a + tuple to one of the fields, ``TypeError`` will be raised. """ __slots__ = [ 'ciphers', 'digests', 'key_types', 'kex', 'compression', '_transport' ] @@ -87,7 +87,7 @@ class SecurityOptions (object): """ Returns a string representation of this object, for debugging. - @rtype: str + :rtype: str """ return '' % repr(self._transport) @@ -192,7 +192,7 @@ class Transport (threading.Thread): """ An SSH Transport attaches to a stream (usually a socket), negotiates an encrypted session, authenticates, and then creates stream tunnels, called - L{Channel}s, across the session. Multiple channels can be multiplexed + :class:`channels `, across the session. Multiple channels can be multiplexed across a single session (and often are, in the case of port forwardings). """ @@ -250,29 +250,29 @@ class Transport (threading.Thread): """ Create a new SSH session over an existing socket, or socket-like object. This only creates the Transport object; it doesn't begin the - SSH session yet. Use L{connect} or L{start_client} to begin a client - session, or L{start_server} to begin a server session. + SSH session yet. Use :class:`connect` or :class:`start_client` to begin a client + session, or :class:`start_server` to begin a server session. If the object is not actually a socket, it must have the following methods: - - C{send(str)}: Writes from 1 to C{len(str)} bytes, and + - ``send(str)``: Writes from 1 to ``len(str)`` bytes, and returns an int representing the number of bytes written. Returns - 0 or raises C{EOFError} if the stream has been closed. - - C{recv(int)}: Reads from 1 to C{int} bytes and returns them as a - string. Returns 0 or raises C{EOFError} if the stream has been + 0 or raises ``EOFError`` if the stream has been closed. + - ``recv(int)``: Reads from 1 to ``int`` bytes and returns them as a + string. Returns 0 or raises ``EOFError`` if the stream has been closed. - - C{close()}: Closes the socket. - - C{settimeout(n)}: Sets a (float) timeout on I/O operations. + - ``close()``: Closes the socket. + - ``settimeout(n)``: Sets a (float) timeout on I/O operations. For ease of use, you may also pass in an address (as a tuple) or a host - string as the C{sock} argument. (A host string is a hostname with an - optional port (separated by C{":"}) which will be converted into a - tuple of C{(hostname, port)}.) A socket will be connected to this - address and used for communication. Exceptions from the C{socket} call + string as the ``sock`` argument. (A host string is a hostname with an + optional port (separated by ``":"``) which will be converted into a + tuple of ``(hostname, port)``.) A socket will be connected to this + address and used for communication. Exceptions from the ``socket`` call may be thrown in this case. - @param sock: a socket or socket-like object to create the session over. - @type sock: socket + :param sock: a socket or socket-like object to create the session over. + :type sock: socket """ if isinstance(sock, (str, unicode)): # convert "host:port" into (host, port) @@ -372,7 +372,7 @@ class Transport (threading.Thread): """ Returns a string representation of this object, for debugging. - @rtype: str + :rtype: str """ out = '} or - L{auth_publickey }. + calling :class:`auth_password ` or + :class:`auth_publickey `. - @note: L{connect} is a simpler method for connecting as a client. + .. note:: :class:`connect` is a simpler method for connecting as a client. - @note: After calling this method (or L{start_server} or L{connect}), + .. note:: After calling this method (or :class:`start_server` or :class:`connect`), you should no longer directly read from or write to the original socket object. - @param event: an event to trigger when negotiation is complete + :param event: an event to trigger when negotiation is complete (optional) - @type event: threading.Event + :type event: threading.Event - @raise SSHException: if negotiation fails (and no C{event} was passed + :raises SSHException: if negotiation fails (and no ``event`` was passed in) """ self.active = True @@ -470,41 +470,41 @@ class Transport (threading.Thread): def start_server(self, event=None, server=None): """ Negotiate a new SSH2 session as a server. This is the first step after - creating a new L{Transport} and setting up your server host key(s). A + creating a new :class:`Transport` and setting up your server host key(s). A separate thread is created for protocol negotiation. If an event is passed in, this method returns immediately. When - negotiation is done (successful or not), the given C{Event} will - be triggered. On failure, L{is_active} will return C{False}. + negotiation is done (successful or not), the given ``Event`` will + be triggered. On failure, :class:`is_active` will return ``False``. - (Since 1.4) If C{event} is C{None}, this method will not return until + (Since 1.4) If ``event`` is ``None``, this method will not return until negotation is done. On success, the method returns normally. Otherwise an SSHException is raised. After a successful negotiation, the client will need to authenticate. Override the methods - L{get_allowed_auths }, - L{check_auth_none }, - L{check_auth_password }, and - L{check_auth_publickey } in the - given C{server} object to control the authentication process. + :class:`get_allowed_auths `, + :class:`check_auth_none `, + :class:`check_auth_password `, and + :class:`check_auth_publickey ` in the + given ``server`` object to control the authentication process. After a successful authentication, the client should request to open a channel. Override - L{check_channel_request } in the - given C{server} object to allow channels to be opened. + :class:`check_channel_request ` in the + given ``server`` object to allow channels to be opened. - @note: After calling this method (or L{start_client} or L{connect}), + .. note:: After calling this method (or :class:`start_client` or :class:`connect`), you should no longer directly read from or write to the original socket object. - @param event: an event to trigger when negotiation is complete. - @type event: threading.Event - @param server: an object used to perform authentication and create - L{Channel}s. - @type server: L{server.ServerInterface} + :param event: an event to trigger when negotiation is complete. + :type event: threading.Event + :param server: an object used to perform authentication and create + :class:`channels ` + :type server: :class:`server.ServerInterface` - @raise SSHException: if negotiation fails (and no C{event} was passed + :raises SSHException: if negotiation fails (and no ``event`` was passed in) """ if server is None: @@ -540,9 +540,9 @@ class Transport (threading.Thread): key info, not just the public half. Only one key of each type (RSA or DSS) is kept. - @param key: the host key to add, usually an L{RSAKey } or - L{DSSKey }. - @type key: L{PKey } + :param key: the host key to add, usually an :class:`RSAKey ` or + :class:`DSSKey `. + :type key: :class:`PKey ` """ self.server_key_dict[key.get_name()] = key @@ -550,15 +550,15 @@ class Transport (threading.Thread): """ Return the active host key, in server mode. After negotiating with the client, this method will return the negotiated host key. If only one - type of host key was set with L{add_server_key}, that's the only key + type of host key was set with :class:`add_server_key`, that's the only key that will ever be returned. But in cases where you have set more than one type of host key (for example, an RSA key and a DSS key), the key type will be negotiated by the client, and this method will return the key of the type agreed on. If the host key has not been negotiated - yet, C{None} is returned. In client mode, the behavior is undefined. + yet, ``None`` is returned. In client mode, the behavior is undefined. - @return: host key of the type negotiated by the client, or C{None}. - @rtype: L{PKey } + :return: host key of the type negotiated by the client, or ``None``. + :rtype: :class:`PKey ` """ try: return self.server_key_dict[self.host_key_type] @@ -568,7 +568,7 @@ class Transport (threading.Thread): def load_server_moduli(filename=None): """ - I{(optional)} + (optional) Load a file of prime moduli for use in doing group-exchange key negotiation in server mode. It's a rather obscure option and can be safely ignored. @@ -577,20 +577,20 @@ class Transport (threading.Thread): negotiation, which asks the server to send a random prime number that fits certain criteria. These primes are pretty difficult to compute, so they can't be generated on demand. But many systems contain a file - of suitable primes (usually named something like C{/etc/ssh/moduli}). - If you call C{load_server_moduli} and it returns C{True}, then this + of suitable primes (usually named something like ``/etc/ssh/moduli``). + If you call ``load_server_moduli`` and it returns ``True``, then this file of primes has been loaded and we will support "group-exchange" in server mode. Otherwise server mode will just claim that it doesn't support that method of key negotiation. - @param filename: optional path to the moduli file, if you happen to + :param filename: optional path to the moduli file, if you happen to know that it's not in a standard location. - @type filename: str - @return: True if a moduli file was successfully loaded; False + :type filename: str + :return: True if a moduli file was successfully loaded; False otherwise. - @rtype: bool + :rtype: bool - @note: This has no effect when used in client mode. + .. note:: This has no effect when used in client mode. """ Transport._modulus_pack = ModulusPack(rng) # places to look for the openssh "moduli" file @@ -624,15 +624,15 @@ class Transport (threading.Thread): """ Return the host key of the server (in client mode). - @note: Previously this call returned a tuple of (key type, key string). + .. note:: Previously this call returned a tuple of (key type, key string). You can get the same effect by calling - L{PKey.get_name } for the key type, and - C{str(key)} for the key string. + :class:`PKey.get_name ` for the key type, and + ``str(key)`` for the key string. - @raise SSHException: if no session is currently active. + :raises SSHException: if no session is currently active. - @return: public key of the remote server - @rtype: L{PKey } + :return: public key of the remote server + :rtype: :class:`PKey ` """ if (not self.active) or (not self.initial_kex_done): raise SSHException('No existing session') @@ -642,37 +642,37 @@ class Transport (threading.Thread): """ Return true if this session is active (open). - @return: True if the session is still active (open); False if the + :return: True if the session is still active (open); False if the session is closed - @rtype: bool + :rtype: bool """ return self.active def open_session(self): """ - Request a new channel to the server, of type C{"session"}. This - is just an alias for C{open_channel('session')}. + Request a new channel to the server, of type ``"session"``. This + is just an alias for ``open_channel('session')``. - @return: a new L{Channel} - @rtype: L{Channel} + :return: a new :class:`Channel` + :rtype: :class:`Channel` - @raise SSHException: if the request is rejected or the session ends + :raises SSHException: if the request is rejected or the session ends prematurely """ return self.open_channel('session') def open_x11_channel(self, src_addr=None): """ - Request a new channel to the client, of type C{"x11"}. This - is just an alias for C{open_channel('x11', src_addr=src_addr)}. + Request a new channel to the client, of type ``"x11"``. This + is just an alias for ``open_channel('x11', src_addr=src_addr)``. - @param src_addr: the source address of the x11 server (port is the + :param src_addr: the source address of the x11 server (port is the x11 port, ie. 6010) - @type src_addr: (str, int) - @return: a new L{Channel} - @rtype: L{Channel} + :type src_addr: (str, int) + :return: a new :class:`Channel` + :rtype: :class:`Channel` - @raise SSHException: if the request is rejected or the session ends + :raises SSHException: if the request is rejected or the session ends prematurely """ return self.open_channel('x11', src_addr=src_addr) @@ -680,51 +680,51 @@ class Transport (threading.Thread): def open_forward_agent_channel(self): """ Request a new channel to the client, of type - C{"auth-agent@openssh.com"}. + ``"auth-agent@openssh.com"``. - This is just an alias for C{open_channel('auth-agent@openssh.com')}. - @return: a new L{Channel} - @rtype: L{Channel} + This is just an alias for ``open_channel('auth-agent@openssh.com')``. + :return: a new :class:`Channel` + :rtype: :class:`Channel` - @raise SSHException: if the request is rejected or the session ends + :raises SSHException: if the request is rejected or the session ends prematurely """ return self.open_channel('auth-agent@openssh.com') def open_forwarded_tcpip_channel(self, (src_addr, src_port), (dest_addr, dest_port)): """ - Request a new channel back to the client, of type C{"forwarded-tcpip"}. + Request a new channel back to the client, of type ``"forwarded-tcpip"``. This is used after a client has requested port forwarding, for sending incoming connections back to the client. - @param src_addr: originator's address - @param src_port: originator's port - @param dest_addr: local (server) connected address - @param dest_port: local (server) connected port + :param src_addr: originator's address + :param src_port: originator's port + :param dest_addr: local (server) connected address + :param dest_port: local (server) connected port """ return self.open_channel('forwarded-tcpip', (dest_addr, dest_port), (src_addr, src_port)) def open_channel(self, kind, dest_addr=None, src_addr=None): """ - Request a new channel to the server. L{Channel}s are socket-like + Request a new channel to the server. :class:`Channels ` are socket-like objects used for the actual transfer of data across the session. You may only request a channel after negotiating encryption (using - L{connect} or L{start_client}) and authenticating. + :class:`connect` or :class:`start_client`) and authenticating. - @param kind: the kind of channel requested (usually C{"session"}, - C{"forwarded-tcpip"}, C{"direct-tcpip"}, or C{"x11"}) - @type kind: str - @param dest_addr: the destination address of this port forwarding, - if C{kind} is C{"forwarded-tcpip"} or C{"direct-tcpip"} (ignored + :param kind: the kind of channel requested (usually ``"session"``, + ``"forwarded-tcpip"``, ``"direct-tcpip"``, or ``"x11"``) + :type kind: str + :param dest_addr: the destination address of this port forwarding, + if ``kind`` is ``"forwarded-tcpip"`` or ``"direct-tcpip"`` (ignored for other channel types) - @type dest_addr: (str, int) - @param src_addr: the source address of this port forwarding, if - C{kind} is C{"forwarded-tcpip"}, C{"direct-tcpip"}, or C{"x11"} - @type src_addr: (str, int) - @return: a new L{Channel} on success - @rtype: L{Channel} - - @raise SSHException: if the request is rejected or the session ends + :type dest_addr: (str, int) + :param src_addr: the source address of this port forwarding, if + ``kind`` is ``"forwarded-tcpip"``, ``"direct-tcpip"``, or ``"x11"`` + :type src_addr: (str, int) + :return: a new :class:`Channel` on success + :rtype: :class:`Channel` + + :raises SSHException: if the request is rejected or the session ends prematurely """ if not self.active: @@ -782,24 +782,24 @@ class Transport (threading.Thread): handler(channel, (origin_addr, origin_port), (server_addr, server_port)) - where C{server_addr} and C{server_port} are the address and port that + where ``server_addr`` and ``server_port`` are the address and port that the server was listening on. If no handler is set, the default behavior is to send new incoming forwarded connections into the accept queue, to be picked up via - L{accept}. + :class:`accept`. - @param address: the address to bind when forwarding - @type address: str - @param port: the port to forward, or 0 to ask the server to allocate + :param address: the address to bind when forwarding + :type address: str + :param port: the port to forward, or 0 to ask the server to allocate any port - @type port: int - @param handler: optional handler for incoming forwarded connections - @type handler: function(Channel, (str, int), (str, int)) - @return: the port # allocated by the server - @rtype: int + :type port: int + :param handler: optional handler for incoming forwarded connections + :type handler: function(Channel, (str, int), (str, int)) + :return: the port # allocated by the server + :rtype: int - @raise SSHException: if the server refused the TCP forward request + :raises SSHException: if the server refused the TCP forward request """ if not self.active: raise SSHException('SSH session not active') @@ -823,10 +823,10 @@ class Transport (threading.Thread): connections to the given address & port will be forwarded across this ssh connection. - @param address: the address to stop forwarding - @type address: str - @param port: the port to stop forwarding - @type port: int + :param address: the address to stop forwarding + :type address: str + :param port: the port to stop forwarding + :type port: int """ if not self.active: return @@ -839,9 +839,9 @@ class Transport (threading.Thread): an SFTP session will be opened with the remote host, and a new SFTPClient object will be returned. - @return: a new L{SFTPClient} object, referring to an sftp session + :return: a new :class:`SFTPClient` object, referring to an sftp session (channel) across this transport - @rtype: L{SFTPClient} + :rtype: :class:`SFTPClient` """ return SFTPClient.from_transport(self) @@ -852,9 +852,9 @@ class Transport (threading.Thread): also be used as a keep-alive for long lived connections traversing firewalls. - @param bytes: the number of random bytes to send in the payload of the + :param bytes: the number of random bytes to send in the payload of the ignored packet -- defaults to a random number from 10 to 41. - @type bytes: int + :type bytes: int """ m = Message() m.add_byte(chr(MSG_IGNORE)) @@ -872,7 +872,7 @@ class Transport (threading.Thread): traffic both ways as the two sides swap keys and do computations. This method returns when the session has switched to new keys. - @raise SSHException: if the key renegotiation failed (which causes the + :raises SSHException: if the key renegotiation failed (which causes the session to end) """ self.completion_event = threading.Event() @@ -891,13 +891,13 @@ class Transport (threading.Thread): def set_keepalive(self, interval): """ Turn on/off keepalive packets (default is off). If this is set, after - C{interval} seconds without sending any data over the connection, a + ``interval`` seconds without sending any data over the connection, a "keepalive" packet will be sent (and ignored by the remote host). This can be useful to keep connections alive over a NAT, for example. - @param interval: seconds to wait before sending a keepalive packet (or + :param interval: seconds to wait before sending a keepalive packet (or 0 to disable keepalives). - @type interval: int + :type interval: int """ self.packetizer.set_keepalive(interval, lambda x=weakref.proxy(self): x.global_request('keepalive@lag.net', wait=False)) @@ -907,18 +907,18 @@ class Transport (threading.Thread): Make a global request to the remote host. These are normally extensions to the SSH2 protocol. - @param kind: name of the request. - @type kind: str - @param data: an optional tuple containing additional data to attach + :param kind: name of the request. + :type kind: str + :param data: an optional tuple containing additional data to attach to the request. - @type data: tuple - @param wait: C{True} if this method should not return until a response - is received; C{False} otherwise. - @type wait: bool - @return: a L{Message} containing possible additional data if the - request was successful (or an empty L{Message} if C{wait} was - C{False}); C{None} if the request was denied. - @rtype: L{Message} + :type data: tuple + :param wait: ``True`` if this method should not return until a response + is received; ``False`` otherwise. + :type wait: bool + :return: a :class:`Message` containing possible additional data if the + request was successful (or an empty :class:`Message` if ``wait`` was + ``False``); ``None`` if the request was denied. + :rtype: :class:`Message` """ if wait: self.completion_event = threading.Event() @@ -943,14 +943,14 @@ class Transport (threading.Thread): def accept(self, timeout=None): """ Return the next channel opened by the client over this transport, in - server mode. If no channel is opened before the given timeout, C{None} + server mode. If no channel is opened before the given timeout, ``None`` is returned. - @param timeout: seconds to wait for a channel, or C{None} to wait + :param timeout: seconds to wait for a channel, or ``None`` to wait forever - @type timeout: int - @return: a new Channel opened by the client - @rtype: L{Channel} + :type timeout: int + :return: a new Channel opened by the client + :rtype: :class:`Channel` """ self.lock.acquire() try: @@ -971,34 +971,34 @@ class Transport (threading.Thread): """ Negotiate an SSH2 session, and optionally verify the server's host key and authenticate using a password or private key. This is a shortcut - for L{start_client}, L{get_remote_server_key}, and - L{Transport.auth_password} or L{Transport.auth_publickey}. Use those + for :class:`start_client`, :class:`get_remote_server_key`, and + :class:`Transport.auth_password` or :class:`Transport.auth_publickey`. Use those methods if you want more control. You can use this method immediately after creating a Transport to negotiate encryption with a server. If it fails, an exception will be thrown. On success, the method will return cleanly, and an encrypted - session exists. You may immediately call L{open_channel} or - L{open_session} to get a L{Channel} object, which is used for data + session exists. You may immediately call :class:`open_channel` or + :class:`open_session` to get a :class:`Channel` object, which is used for data transfer. - @note: If you fail to supply a password or private key, this method may - succeed, but a subsequent L{open_channel} or L{open_session} call may + .. note:: If you fail to supply a password or private key, this method may + succeed, but a subsequent :class:`open_channel` or :class:`open_session` call may fail because you haven't authenticated yet. - @param hostkey: the host key expected from the server, or C{None} if + :param hostkey: the host key expected from the server, or ``None`` if you don't want to do host key verification. - @type hostkey: L{PKey} - @param username: the username to authenticate as. - @type username: str - @param password: a password to use for authentication, if you want to - use password authentication; otherwise C{None}. - @type password: str - @param pkey: a private key to use for authentication, if you want to - use private key authentication; otherwise C{None}. - @type pkey: L{PKey} - - @raise SSHException: if the SSH2 negotiation fails, the host key + :type hostkey: :class:`PKey` + :param username: the username to authenticate as. + :type username: str + :param password: a password to use for authentication, if you want to + use password authentication; otherwise ``None``. + :type password: str + :param pkey: a private key to use for authentication, if you want to + use private key authentication; otherwise ``None``. + :type pkey: :class:`PKey` + + :raises SSHException: if the SSH2 negotiation fails, the host key supplied by the server is incorrect, or authentication fails. """ if hostkey is not None: @@ -1030,13 +1030,13 @@ class Transport (threading.Thread): """ Return any exception that happened during the last server request. This can be used to fetch more specific error information after using - calls like L{start_client}. The exception (if any) is cleared after + calls like :class:`start_client`. The exception (if any) is cleared after this call. - @return: an exception, or C{None} if there is no stored exception. - @rtype: Exception + :return: an exception, or ``None`` if there is no stored exception. + :rtype: Exception - @since: 1.1 + .. versionadded:: 1.1 """ self.lock.acquire() try: @@ -1050,17 +1050,17 @@ class Transport (threading.Thread): """ Set the handler class for a subsystem in server mode. If a request for this subsystem is made on an open ssh channel later, this handler - will be constructed and called -- see L{SubsystemHandler} for more + will be constructed and called -- see :class:`SubsystemHandler` for more detailed documentation. Any extra parameters (including keyword arguments) are saved and - passed to the L{SubsystemHandler} constructor later. + passed to the :class:`SubsystemHandler` constructor later. - @param name: name of the subsystem. - @type name: str - @param handler: subclass of L{SubsystemHandler} that handles this + :param name: name of the subsystem. + :type name: str + :param handler: subclass of :class:`SubsystemHandler` that handles this subsystem. - @type handler: class + :type handler: class """ try: self.lock.acquire() @@ -1072,10 +1072,10 @@ class Transport (threading.Thread): """ Return true if this session is active and authenticated. - @return: True if the session is still open and has been authenticated + :return: True if the session is still open and has been authenticated successfully; False if authentication failed and/or the session is closed. - @rtype: bool + :rtype: bool """ return self.active and (self.auth_handler is not None) and self.auth_handler.is_authenticated() @@ -1083,10 +1083,10 @@ class Transport (threading.Thread): """ Return the username this connection is authenticated for. If the session is not authenticated (or authentication failed), this method - returns C{None}. + returns ``None``. - @return: username that was authenticated, or C{None}. - @rtype: string + :return: username that was authenticated, or ``None``. + :rtype: string """ if not self.active or (self.auth_handler is None): return None @@ -1097,20 +1097,20 @@ class Transport (threading.Thread): Try to authenticate to the server using no authentication at all. This will almost always fail. It may be useful for determining the list of authentication types supported by the server, by catching the - L{BadAuthenticationType} exception raised. + :class:`BadAuthenticationType` exception raised. - @param username: the username to authenticate as - @type username: string - @return: list of auth types permissible for the next stage of + :param username: the username to authenticate as + :type username: string + :return: list of auth types permissible for the next stage of authentication (normally empty) - @rtype: list + :rtype: list - @raise BadAuthenticationType: if "none" authentication isn't allowed + :raises BadAuthenticationType: if "none" authentication isn't allowed by the server for this user - @raise SSHException: if the authentication failed due to a network + :raises SSHException: if the authentication failed due to a network error - @since: 1.5 + .. versionadded:: 1.5 """ if (not self.active) or (not self.initial_kex_done): raise SSHException('No existing session') @@ -1124,16 +1124,16 @@ class Transport (threading.Thread): Authenticate to the server using a password. The username and password are sent over an encrypted link. - If an C{event} is passed in, this method will return immediately, and + If an ``event`` is passed in, this method will return immediately, and the event will be triggered once authentication succeeds or fails. On - success, L{is_authenticated} will return C{True}. On failure, you may - use L{get_exception} to get more detailed error information. + success, :class:`is_authenticated` will return ``True``. On failure, you may + use :class:`get_exception` to get more detailed error information. Since 1.1, if no event is passed, this method will block until the authentication succeeds or fails. On failure, an exception is raised. Otherwise, the method simply returns. - Since 1.5, if no event is passed and C{fallback} is C{True} (the + Since 1.5, if no event is passed and ``fallback`` is ``True`` (the default), if the server doesn't support plain password authentication but does support so-called "keyboard-interactive" mode, an attempt will be made to authenticate using this interactive mode. If it fails, @@ -1146,26 +1146,26 @@ class Transport (threading.Thread): this method will return a list of auth types permissible for the next step. Otherwise, in the normal case, an empty list is returned. - @param username: the username to authenticate as - @type username: str - @param password: the password to authenticate with - @type password: str or unicode - @param event: an event to trigger when the authentication attempt is + :param username: the username to authenticate as + :type username: str + :param password: the password to authenticate with + :type password: str or unicode + :param event: an event to trigger when the authentication attempt is complete (whether it was successful or not) - @type event: threading.Event - @param fallback: C{True} if an attempt at an automated "interactive" + :type event: threading.Event + :param fallback: ``True`` if an attempt at an automated "interactive" password auth should be made if the server doesn't support normal password auth - @type fallback: bool - @return: list of auth types permissible for the next stage of + :type fallback: bool + :return: list of auth types permissible for the next stage of authentication (normally empty) - @rtype: list + :rtype: list - @raise BadAuthenticationType: if password authentication isn't + :raises BadAuthenticationType: if password authentication isn't allowed by the server for this user (and no event was passed in) - @raise AuthenticationException: if the authentication failed (and no + :raises AuthenticationException: if the authentication failed (and no event was passed in) - @raise SSHException: if there was a network error + :raises SSHException: if there was a network error """ if (not self.active) or (not self.initial_kex_done): # we should never try to send the password unless we're on a secure link @@ -1207,10 +1207,10 @@ class Transport (threading.Thread): Authenticate to the server using a private key. The key is used to sign data from the server, so it must include the private part. - If an C{event} is passed in, this method will return immediately, and + If an ``event`` is passed in, this method will return immediately, and the event will be triggered once authentication succeeds or fails. On - success, L{is_authenticated} will return C{True}. On failure, you may - use L{get_exception} to get more detailed error information. + success, :class:`is_authenticated` will return ``True``. On failure, you may + use :class:`get_exception` to get more detailed error information. Since 1.1, if no event is passed, this method will block until the authentication succeeds or fails. On failure, an exception is raised. @@ -1220,22 +1220,22 @@ class Transport (threading.Thread): this method will return a list of auth types permissible for the next step. Otherwise, in the normal case, an empty list is returned. - @param username: the username to authenticate as - @type username: string - @param key: the private key to authenticate with - @type key: L{PKey } - @param event: an event to trigger when the authentication attempt is + :param username: the username to authenticate as + :type username: string + :param key: the private key to authenticate with + :type key: :class:`PKey ` + :param event: an event to trigger when the authentication attempt is complete (whether it was successful or not) - @type event: threading.Event - @return: list of auth types permissible for the next stage of + :type event: threading.Event + :return: list of auth types permissible for the next stage of authentication (normally empty) - @rtype: list + :rtype: list - @raise BadAuthenticationType: if public-key authentication isn't + :raises BadAuthenticationType: if public-key authentication isn't allowed by the server for this user (and no event was passed in) - @raise AuthenticationException: if the authentication failed (and no + :raises AuthenticationException: if the authentication failed (and no event was passed in) - @raise SSHException: if there was a network error + :raises SSHException: if there was a network error """ if (not self.active) or (not self.initial_kex_done): # we should never try to authenticate unless we're on a secure link @@ -1263,15 +1263,15 @@ class Transport (threading.Thread): if the server continues to ask questions. The handler is expected to be a callable that will handle calls of the - form: C{handler(title, instructions, prompt_list)}. The C{title} is - meant to be a dialog-window title, and the C{instructions} are user - instructions (both are strings). C{prompt_list} will be a list of - prompts, each prompt being a tuple of C{(str, bool)}. The string is + form: ``handler(title, instructions, prompt_list)``. The ``title`` is + meant to be a dialog-window title, and the ``instructions`` are user + instructions (both are strings). ``prompt_list`` will be a list of + prompts, each prompt being a tuple of ``(str, bool)``. The string is the prompt and the boolean indicates whether the user text should be echoed. A sample call would thus be: - C{handler('title', 'instructions', [('Password:', False)])}. + ``handler('title', 'instructions', [('Password:', False)])``. The handler should return a list or tuple of answers to the server's questions. @@ -1280,22 +1280,22 @@ class Transport (threading.Thread): this method will return a list of auth types permissible for the next step. Otherwise, in the normal case, an empty list is returned. - @param username: the username to authenticate as - @type username: string - @param handler: a handler for responding to server questions - @type handler: callable - @param submethods: a string list of desired submethods (optional) - @type submethods: str - @return: list of auth types permissible for the next stage of + :param username: the username to authenticate as + :type username: string + :param handler: a handler for responding to server questions + :type handler: callable + :param submethods: a string list of desired submethods (optional) + :type submethods: str + :return: list of auth types permissible for the next stage of authentication (normally empty). - @rtype: list + :rtype: list - @raise BadAuthenticationType: if public-key authentication isn't + :raises BadAuthenticationType: if public-key authentication isn't allowed by the server for this user - @raise AuthenticationException: if the authentication failed - @raise SSHException: if there was a network error + :raises AuthenticationException: if the authentication failed + :raises SSHException: if there was a network error - @since: 1.5 + .. versionadded:: 1.5 """ if (not self.active) or (not self.initial_kex_done): # we should never try to authenticate unless we're on a secure link @@ -1308,14 +1308,14 @@ class Transport (threading.Thread): def set_log_channel(self, name): """ Set the channel for this transport's logging. The default is - C{"paramiko.transport"} but it can be set to anything you want. - (See the C{logging} module for more info.) SSH Channels will log + ``"paramiko.transport"`` but it can be set to anything you want. + (See the ``logging`` module for more info.) SSH Channels will log to a sub-channel of the one specified. - @param name: new channel name for logging - @type name: str + :param name: new channel name for logging + :type name: str - @since: 1.1 + .. versionadded:: 1.1 """ self.log_name = name self.logger = util.get_logger(name) @@ -1325,10 +1325,10 @@ class Transport (threading.Thread): """ Return the channel name used for this transport's logging. - @return: channel name. - @rtype: str + :return: channel name. + :rtype: str - @since: 1.2 + .. versionadded:: 1.2 """ return self.log_name @@ -1338,35 +1338,35 @@ class Transport (threading.Thread): the logs. Normally you would want this off (which is the default), but if you are debugging something, it may be useful. - @param hexdump: C{True} to log protocol traffix (in hex) to the log; - C{False} otherwise. - @type hexdump: bool + :param hexdump: ``True`` to log protocol traffix (in hex) to the log; + ``False`` otherwise. + :type hexdump: bool """ self.packetizer.set_hexdump(hexdump) def get_hexdump(self): """ - Return C{True} if the transport is currently logging hex dumps of + Return ``True`` if the transport is currently logging hex dumps of protocol traffic. - @return: C{True} if hex dumps are being logged - @rtype: bool + :return: ``True`` if hex dumps are being logged + :rtype: bool - @since: 1.4 + .. versionadded:: 1.4 """ return self.packetizer.get_hexdump() def use_compression(self, compress=True): """ Turn on/off compression. This will only have an affect before starting - the transport (ie before calling L{connect}, etc). By default, + the transport (ie before calling :class:`connect`, etc). By default, compression is off since it negatively affects interactive sessions. - @param compress: C{True} to ask the remote client/server to compress - traffic; C{False} to refuse compression - @type compress: bool + :param compress: ``True`` to ask the remote client/server to compress + traffic; ``False`` to refuse compression + :type compress: bool - @since: 1.5.2 + .. versionadded:: 1.5.2 """ if compress: self._preferred_compression = ( 'zlib@openssh.com', 'zlib', 'none' ) @@ -1376,12 +1376,12 @@ class Transport (threading.Thread): def getpeername(self): """ Return the address of the remote side of this Transport, if possible. - This is effectively a wrapper around C{'getpeername'} on the underlying - socket. If the socket-like object has no C{'getpeername'} method, - then C{("unknown", 0)} is returned. + This is effectively a wrapper around ``'getpeername'`` on the underlying + socket. If the socket-like object has no ``'getpeername'`` method, + then ``("unknown", 0)`` is returned. - @return: the address if the remote host, if known - @rtype: tuple(str, int) + :return: the address if the remote host, if known + :rtype: tuple(str, int) """ gp = getattr(self.sock, 'getpeername', None) if gp is None: diff --git a/paramiko/util.py b/paramiko/util.py index 85ee6b06..65c16dc5 100644 --- a/paramiko/util.py +++ b/paramiko/util.py @@ -154,17 +154,17 @@ def generate_key_bytes(hashclass, salt, key, nbytes): through a secure hash into some keyworthy bytes. This specific algorithm is used for encrypting/decrypting private key files. - @param hashclass: class from L{Crypto.Hash} that can be used as a secure - hashing function (like C{MD5} or C{SHA}). - @type hashclass: L{Crypto.Hash} - @param salt: data to salt the hash with. - @type salt: string - @param key: human-entered password or passphrase. - @type key: string - @param nbytes: number of bytes to generate. - @type nbytes: int - @return: key data - @rtype: string + :param hashclass: class from :class:`Crypto.Hash` that can be used as a secure + hashing function (like ``MD5`` or ``SHA``). + :type hashclass: :class:`Crypto.Hash` + :param salt: data to salt the hash with. + :type salt: string + :param key: human-entered password or passphrase. + :type key: string + :param nbytes: number of bytes to generate. + :type nbytes: int + :return: key data + :rtype: string """ keydata = '' digest = '' @@ -185,26 +185,26 @@ def generate_key_bytes(hashclass, salt, key, nbytes): def load_host_keys(filename): """ Read a file of known SSH host keys, in the format used by openssh, and - return a compound dict of C{hostname -> keytype ->} L{PKey }. + return a compound dict of ``hostname -> keytype ->`` :class:`PKey `. The hostname may be an IP address or DNS name. The keytype will be either - C{"ssh-rsa"} or C{"ssh-dss"}. + ``"ssh-rsa"`` or ``"ssh-dss"``. This type of file unfortunately doesn't exist on Windows, but on posix, - it will usually be stored in C{os.path.expanduser("~/.ssh/known_hosts")}. + it will usually be stored in ``os.path.expanduser("~/.ssh/known_hosts")``. - Since 1.5.3, this is just a wrapper around L{HostKeys}. + Since 1.5.3, this is just a wrapper around :class:`HostKeys`. - @param filename: name of the file to read host keys from - @type filename: str - @return: dict of host keys, indexed by hostname and then keytype - @rtype: dict(hostname, dict(keytype, L{PKey })) + :param filename: name of the file to read host keys from + :type filename: str + :return: dict of host keys, indexed by hostname and then keytype + :rtype: dict(hostname, dict(keytype, :class:`PKey `)) """ from paramiko.hostkeys import HostKeys return HostKeys(filename) def parse_ssh_config(file_obj): """ - Provided only as a backward-compatible wrapper around L{SSHConfig}. + Provided only as a backward-compatible wrapper around :class:`SSHConfig`. """ config = SSHConfig() config.parse(file_obj) @@ -212,7 +212,7 @@ def parse_ssh_config(file_obj): def lookup_ssh_host_config(hostname, config): """ - Provided only as a backward-compatible wrapper around L{SSHConfig}. + Provided only as a backward-compatible wrapper around :class:`SSHConfig`. """ return config.lookup(hostname) diff --git a/sites/docs/api.rst b/sites/docs/api.rst new file mode 100644 index 00000000..47615709 --- /dev/null +++ b/sites/docs/api.rst @@ -0,0 +1,8 @@ +.. _api: + +API +=== + +.. automodule:: paramiko + :members: + :special-members: diff --git a/sites/docs/conf.py b/sites/docs/conf.py index 0c7ffe55..94267f0a 100644 --- a/sites/docs/conf.py +++ b/sites/docs/conf.py @@ -1,4 +1,7 @@ # Obtain shared config values import os, sys sys.path.append(os.path.abspath('..')) +sys.path.append(os.path.abspath('../..')) from shared_conf import * + +extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx'] -- cgit v1.2.3 From 87cd72c144c54fc9c6f05ff7482bd6e9e7622730 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Thu, 23 Jan 2014 11:43:34 -0800 Subject: Set up Intersphinx so www can ref docs --- sites/shared_conf.py | 2 +- sites/www/conf.py | 25 ++++++++++++++++++++----- 2 files changed, 21 insertions(+), 6 deletions(-) (limited to 'sites') diff --git a/sites/shared_conf.py b/sites/shared_conf.py index 89e0a56d..c48dcdce 100644 --- a/sites/shared_conf.py +++ b/sites/shared_conf.py @@ -42,7 +42,7 @@ html_sidebars = { # Regular settings project = u'Paramiko' year = datetime.now().year -copyright = u'%d Jeff Forcier, 2003-2012 Robey Pointer' % year +copyright = u'2013-%d Jeff Forcier, 2003-2012 Robey Pointer' % year master_doc = 'index' templates_path = ['_templates'] exclude_trees = ['_build'] diff --git a/sites/www/conf.py b/sites/www/conf.py index c144b5b4..b2f96186 100644 --- a/sites/www/conf.py +++ b/sites/www/conf.py @@ -1,15 +1,30 @@ # Obtain shared config values -import os, sys -sys.path.append(os.path.abspath('..')) +import sys +import os +from os.path import abspath, join, dirname + +sys.path.append(abspath(join(dirname(__file__), '..'))) from shared_conf import * -# Add local blog extension -sys.path.append(os.path.abspath('.')) +# Local blog extension +sys.path.append(abspath('.')) extensions = ['blog'] rss_link = 'http://paramiko.org' rss_description = 'Paramiko project news' -# Add Releases changelog extension +# Releases changelog extension extensions.append('releases') releases_release_uri = "https://github.com/paramiko/paramiko/tree/%s" releases_issue_uri = "https://github.com/paramiko/paramiko/issues/%s" + +# Intersphinx for referencing API/usage docs +extensions.append('sphinx.ext.intersphinx') +# Default is 'local' building, but reference the public docs site when building +# under RTD. +target = join(dirname(__file__), '..', 'docs', '_build') +if os.environ.get('READTHEDOCS') == 'True': + # TODO: switch to docs.paramiko.org post go-live + target = 'http://paramiko-docs.readthedocs.org/en/latest/' +intersphinx_mapping = { + 'docs': (target, None), +} -- cgit v1.2.3 From 69d40710dc55373f9bbeb9f2721c6942a5250bbd Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Tue, 28 Jan 2014 08:46:21 -0800 Subject: Tweak logo settings (& rely on new alabaster defaults) --- dev-requirements.txt | 2 +- sites/shared_conf.py | 2 -- 2 files changed, 1 insertion(+), 3 deletions(-) (limited to 'sites') diff --git a/dev-requirements.txt b/dev-requirements.txt index a2b9a4e8..a967765c 100644 --- a/dev-requirements.txt +++ b/dev-requirements.txt @@ -3,5 +3,5 @@ invoke>=0.6.1 invocations>=0.4.4 sphinx>=1.1.3 -alabaster>=0.1.0 +alabaster>=0.2.0 releases>=0.2.4 diff --git a/sites/shared_conf.py b/sites/shared_conf.py index c48dcdce..d6852cc7 100644 --- a/sites/shared_conf.py +++ b/sites/shared_conf.py @@ -11,8 +11,6 @@ html_theme_path = [alabaster.get_path()] html_static_path = ['../_shared_static'] html_theme = 'alabaster' html_theme_options = { - 'logo': 'logo.png', - 'logo_name': 'true', 'description': "A Python implementation of SSHv2.", 'github_user': 'paramiko', 'github_repo': 'paramiko', -- cgit v1.2.3 From da51cd8b14231a3fa9850d0d1b939168ae7b0534 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Tue, 28 Jan 2014 12:50:19 -0800 Subject: Update to new alabaster-driven nav sidebar --- sites/shared_conf.py | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) (limited to 'sites') diff --git a/sites/shared_conf.py b/sites/shared_conf.py index d6852cc7..267b3bc2 100644 --- a/sites/shared_conf.py +++ b/sites/shared_conf.py @@ -17,21 +17,18 @@ html_theme_options = { 'gittip_user': 'bitprophet', 'analytics_id': 'UA-18486793-2', + 'extra_nav_links': { + "API Docs": 'http://docs.paramiko.org', + }, + 'link': '#3782BE', 'link_hover': '#3782BE', } html_sidebars = { - # Landing page (no ToC) - 'index': [ - 'about.html', - 'searchbox.html', - 'donate.html', - ], - # Inner pages get a ToC '**': [ 'about.html', - 'localtoc.html', + 'navigation.html', 'searchbox.html', 'donate.html', ] -- cgit v1.2.3 From 7b690707dd81a80c7550c1f537b870805418d6df Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Tue, 28 Jan 2014 12:50:24 -0800 Subject: Don't display blog for now --- sites/www/index.rst | 1 - 1 file changed, 1 deletion(-) (limited to 'sites') diff --git a/sites/www/index.rst b/sites/www/index.rst index f8db6fd0..43c060b9 100644 --- a/sites/www/index.rst +++ b/sites/www/index.rst @@ -12,7 +12,6 @@ usage and API documentation can be found at our code documentation site, `docs.paramiko.org `_. .. toctree:: - blog changelog installing contributing -- cgit v1.2.3 From b60075c7cd2fb4dd67701382f953e454d3db1848 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Tue, 28 Jan 2014 16:00:03 -0800 Subject: Prevent warning about unlinked blog page --- sites/www/index.rst | 7 +++++++ 1 file changed, 7 insertions(+) (limited to 'sites') diff --git a/sites/www/index.rst b/sites/www/index.rst index 43c060b9..7fefedd2 100644 --- a/sites/www/index.rst +++ b/sites/www/index.rst @@ -17,6 +17,13 @@ usage and API documentation can be found at our code documentation site, contributing contact +.. Hide blog in hidden toctree for now (to avoid warnings.) + +.. toctree:: + :hidden: + + blog + .. rubric:: Footnotes -- cgit v1.2.3 From 2b0f834c1660c8865300e27b46a85de2edf4d556 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Wed, 29 Jan 2014 14:23:46 -0800 Subject: Move API doc sister link to www site only, derp --- sites/shared_conf.py | 5 ----- sites/www/conf.py | 5 +++++ 2 files changed, 5 insertions(+), 5 deletions(-) (limited to 'sites') diff --git a/sites/shared_conf.py b/sites/shared_conf.py index 267b3bc2..2b98654f 100644 --- a/sites/shared_conf.py +++ b/sites/shared_conf.py @@ -17,13 +17,8 @@ html_theme_options = { 'gittip_user': 'bitprophet', 'analytics_id': 'UA-18486793-2', - 'extra_nav_links': { - "API Docs": 'http://docs.paramiko.org', - }, - 'link': '#3782BE', 'link_hover': '#3782BE', - } html_sidebars = { '**': [ diff --git a/sites/www/conf.py b/sites/www/conf.py index b2f96186..58132d70 100644 --- a/sites/www/conf.py +++ b/sites/www/conf.py @@ -28,3 +28,8 @@ if os.environ.get('READTHEDOCS') == 'True': intersphinx_mapping = { 'docs': (target, None), } + +# Sister-site links to API docs +html_theme_options['extra_nav_links'] = { + "API Docs": 'http://docs.paramiko.org', +} -- cgit v1.2.3 From b8d1724f5714c27ad02ae013e87f5531aec041ea Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Wed, 29 Jan 2014 14:24:54 -0800 Subject: Comment out intersphinx pending #256 --- sites/www/conf.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'sites') diff --git a/sites/www/conf.py b/sites/www/conf.py index 58132d70..1f11c1e2 100644 --- a/sites/www/conf.py +++ b/sites/www/conf.py @@ -23,11 +23,11 @@ extensions.append('sphinx.ext.intersphinx') # under RTD. target = join(dirname(__file__), '..', 'docs', '_build') if os.environ.get('READTHEDOCS') == 'True': - # TODO: switch to docs.paramiko.org post go-live + # TODO: switch to docs.paramiko.org post go-live of sphinx API docs target = 'http://paramiko-docs.readthedocs.org/en/latest/' -intersphinx_mapping = { - 'docs': (target, None), -} +#intersphinx_mapping = { +# 'docs': (target, None), +#} # Sister-site links to API docs html_theme_options['extra_nav_links'] = { -- cgit v1.2.3 From 2b64ff4cd9921b90210b75720c452dcd4e74fe68 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Wed, 29 Jan 2014 15:05:52 -0800 Subject: Forgot to update backticks for Sphinx, derp --- sites/www/changelog.rst | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) (limited to 'sites') diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst index bba78949..71344613 100644 --- a/sites/www/changelog.rst +++ b/sites/www/changelog.rst @@ -14,7 +14,7 @@ Changelog * :bug:`179` Fix a missing variable causing errors when an ssh_config file has a non-default AddressFamily set. Thanks to Ed Marshall & Tomaz Muraus for catch & patch. -* :bug:`200` Fix an exception-causing typo in `demo_simple.py`. Thanks to Alex +* :bug:`200` Fix an exception-causing typo in ``demo_simple.py``. Thanks to Alex Buchanan for catch & Dave Foster for patch. * :bug:`199` Typo fix in the license header cross-project. Thanks to Armin Ronacher for catch & patch. @@ -27,7 +27,7 @@ Changelog and 'remoteforward' keys. Thanks to Emre Yılmaz for the patch. * :release:`1.10.2 <2013-07-26>` * :bug:`153` (also :issue:`67`) Warn on parse failure when reading known_hosts - file. Thanks to `@glasserc` for patch. + file. Thanks to ``@glasserc`` for patch. * :bug:`146` Indentation fixes for readability. Thanks to Abhinav Upadhyay for catch & patch. * :release:`1.10.1 <2013-04-05>` @@ -46,32 +46,32 @@ Changelog attempt to wait for a response from the remote sshd; this fixes problems with less common targets such as some Cisco devices. Thanks to Phillip Heller for catch & patch. -* :feature:`93` Overhaul SSH config parsing to be in line with `man - ssh_config` (& the behavior of `ssh` itself), including addition of parameter +* :feature:`93` Overhaul SSH config parsing to be in line with ``man + ssh_config`` (& the behavior of ``ssh`` itself), including addition of parameter expansion within config values. Thanks to Olle Lundberg for the patch. -* :feature:`110` Honor SSH config `AddressFamily` setting when looking up +* :feature:`110` Honor SSH config ``AddressFamily`` setting when looking up local host's FQDN. Thanks to John Hensley for the patch. * :feature:`128` Defer FQDN resolution until needed, when parsing SSH config files. Thanks to Parantapa Bhattacharya for catch & patch. * :bug:`102 major` Forego random padding for packets when running under - `*-ctr` ciphers. This corrects some slowdowns on platforms where random byte - generation is inefficient (e.g. Windows). Thanks to `@warthog618` for catch + ``*-ctr`` ciphers. This corrects some slowdowns on platforms where random byte + generation is inefficient (e.g. Windows). Thanks to ``@warthog618` for catch & patch, and Michael van der Kolff for code/technique review. -* :feature:`127` Turn `SFTPFile` into a context manager. Thanks to Michael +* :feature:`127` Turn ``SFTPFile`` into a context manager. Thanks to Michael Williamson for the patch. -* :feature:`116` Limit `Message.get_bytes` to an upper bound of 1MB to protect - against potential DoS vectors. Thanks to `@mvschaik` for catch & patch. -* :feature:`115` Add convenience `get_pty` kwarg to `Client.exec_command` so +* :feature:`116` Limit ``Message.get_bytes`` to an upper bound of 1MB to protect + against potential DoS vectors. Thanks to ``@mvschaik`` for catch & patch. +* :feature:`115` Add convenience ``get_pty`` kwarg to ``Client.exec_command`` so users not manually controlling a channel object can still toggle PTY creation. Thanks to Michael van der Kolff for the patch. -* :feature:`71` Add `SFTPClient.putfo` and `.getfo` methods to allow direct +* :feature:`71` Add ``SFTPClient.putfo`` and ``.getfo`` methods to allow direct uploading/downloading of file-like objects. Thanks to Eric Buehl for the patch. -* :feature:`113` Add `timeout` parameter to `SSHClient.exec_command` for +* :feature:`113` Add ``timeout`` parameter to ``SSHClient.exec_command`` for easier setting of the command's internal channel object's timeout. Thanks to Cernov Vladimir for the patch. * :support:`94` Remove duplication of SSH port constant. Thanks to Olle Lundberg for the catch. * :feature:`80` Expose the internal "is closed" property of the file transfer - class `BufferedFile` as `.closed`, better conforming to Python's file - interface. Thanks to `@smunaut` and James Hiscock for catch & patch. + class ``BufferedFile`` as ``.closed``, better conforming to Python's file + interface. Thanks to ``@smunaut`` and James Hiscock for catch & patch. -- cgit v1.2.3 From 34320dfd61ba97f7f302166365b244400abc0857 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Wed, 29 Jan 2014 15:05:52 -0800 Subject: Forgot to update backticks for Sphinx, derp --- sites/www/changelog.rst | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) (limited to 'sites') diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst index bba78949..71344613 100644 --- a/sites/www/changelog.rst +++ b/sites/www/changelog.rst @@ -14,7 +14,7 @@ Changelog * :bug:`179` Fix a missing variable causing errors when an ssh_config file has a non-default AddressFamily set. Thanks to Ed Marshall & Tomaz Muraus for catch & patch. -* :bug:`200` Fix an exception-causing typo in `demo_simple.py`. Thanks to Alex +* :bug:`200` Fix an exception-causing typo in ``demo_simple.py``. Thanks to Alex Buchanan for catch & Dave Foster for patch. * :bug:`199` Typo fix in the license header cross-project. Thanks to Armin Ronacher for catch & patch. @@ -27,7 +27,7 @@ Changelog and 'remoteforward' keys. Thanks to Emre Yılmaz for the patch. * :release:`1.10.2 <2013-07-26>` * :bug:`153` (also :issue:`67`) Warn on parse failure when reading known_hosts - file. Thanks to `@glasserc` for patch. + file. Thanks to ``@glasserc`` for patch. * :bug:`146` Indentation fixes for readability. Thanks to Abhinav Upadhyay for catch & patch. * :release:`1.10.1 <2013-04-05>` @@ -46,32 +46,32 @@ Changelog attempt to wait for a response from the remote sshd; this fixes problems with less common targets such as some Cisco devices. Thanks to Phillip Heller for catch & patch. -* :feature:`93` Overhaul SSH config parsing to be in line with `man - ssh_config` (& the behavior of `ssh` itself), including addition of parameter +* :feature:`93` Overhaul SSH config parsing to be in line with ``man + ssh_config`` (& the behavior of ``ssh`` itself), including addition of parameter expansion within config values. Thanks to Olle Lundberg for the patch. -* :feature:`110` Honor SSH config `AddressFamily` setting when looking up +* :feature:`110` Honor SSH config ``AddressFamily`` setting when looking up local host's FQDN. Thanks to John Hensley for the patch. * :feature:`128` Defer FQDN resolution until needed, when parsing SSH config files. Thanks to Parantapa Bhattacharya for catch & patch. * :bug:`102 major` Forego random padding for packets when running under - `*-ctr` ciphers. This corrects some slowdowns on platforms where random byte - generation is inefficient (e.g. Windows). Thanks to `@warthog618` for catch + ``*-ctr`` ciphers. This corrects some slowdowns on platforms where random byte + generation is inefficient (e.g. Windows). Thanks to ``@warthog618` for catch & patch, and Michael van der Kolff for code/technique review. -* :feature:`127` Turn `SFTPFile` into a context manager. Thanks to Michael +* :feature:`127` Turn ``SFTPFile`` into a context manager. Thanks to Michael Williamson for the patch. -* :feature:`116` Limit `Message.get_bytes` to an upper bound of 1MB to protect - against potential DoS vectors. Thanks to `@mvschaik` for catch & patch. -* :feature:`115` Add convenience `get_pty` kwarg to `Client.exec_command` so +* :feature:`116` Limit ``Message.get_bytes`` to an upper bound of 1MB to protect + against potential DoS vectors. Thanks to ``@mvschaik`` for catch & patch. +* :feature:`115` Add convenience ``get_pty`` kwarg to ``Client.exec_command`` so users not manually controlling a channel object can still toggle PTY creation. Thanks to Michael van der Kolff for the patch. -* :feature:`71` Add `SFTPClient.putfo` and `.getfo` methods to allow direct +* :feature:`71` Add ``SFTPClient.putfo`` and ``.getfo`` methods to allow direct uploading/downloading of file-like objects. Thanks to Eric Buehl for the patch. -* :feature:`113` Add `timeout` parameter to `SSHClient.exec_command` for +* :feature:`113` Add ``timeout`` parameter to ``SSHClient.exec_command`` for easier setting of the command's internal channel object's timeout. Thanks to Cernov Vladimir for the patch. * :support:`94` Remove duplication of SSH port constant. Thanks to Olle Lundberg for the catch. * :feature:`80` Expose the internal "is closed" property of the file transfer - class `BufferedFile` as `.closed`, better conforming to Python's file - interface. Thanks to `@smunaut` and James Hiscock for catch & patch. + class ``BufferedFile`` as ``.closed``, better conforming to Python's file + interface. Thanks to ``@smunaut`` and James Hiscock for catch & patch. -- cgit v1.2.3 From 6646e36673d97803cf48804eb68a73c5e5827461 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Wed, 29 Jan 2014 15:06:14 -0800 Subject: Add 1.11.0 to new changelog --- sites/www/changelog.rst | 15 +++++++++++++++ 1 file changed, 15 insertions(+) (limited to 'sites') diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst index 71344613..5dfbcbbc 100644 --- a/sites/www/changelog.rst +++ b/sites/www/changelog.rst @@ -25,7 +25,22 @@ Changelog Thanks to Jonathan Halcrow for catch & patch. * :bug:`168` Update config handling to properly handle multiple 'localforward' and 'remoteforward' keys. Thanks to Emre Yılmaz for the patch. +* :release:`1.11.0 <2013-07-26>` * :release:`1.10.2 <2013-07-26>` +* :bug:`98 major` On Windows, when interacting with the PuTTY PAgeant, Paramiko + now creates the shared memory map with explicit Security Attributes of the + user, which is the same technique employed by the canonical PuTTY library to + avoid permissions issues when Paramiko is running under a different UAC + context than the PuTTY Ageant process. Thanks to Jason R. Coombs for the + patch. +* :support:`100` Remove use of PyWin32 in ``win_pageant`` module. Module was + already dependent on ctypes for constructing appropriate structures and had + ctypes implementations of all functionality. Thanks to Jason R. Coombs for + the patch. +* :bug:`87 major` Ensure updates to ``known_hosts`` files account for any + updates to said files after Paramiko initially read them. (Includes related + fix to guard against duplicate entries during subsequent ``known_hosts`` + loads.) Thanks to ``@sunweaver`` for the contribution. * :bug:`153` (also :issue:`67`) Warn on parse failure when reading known_hosts file. Thanks to ``@glasserc`` for patch. * :bug:`146` Indentation fixes for readability. Thanks to Abhinav Upadhyay for -- cgit v1.2.3 From a58ee1c89ac49bc7b250d9350bcedf59cad70fc9 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Wed, 29 Jan 2014 15:16:04 -0800 Subject: Missed a spot w/ SnR --- sites/www/changelog.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'sites') diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst index 5dfbcbbc..741374ce 100644 --- a/sites/www/changelog.rst +++ b/sites/www/changelog.rst @@ -69,9 +69,9 @@ Changelog * :feature:`128` Defer FQDN resolution until needed, when parsing SSH config files. Thanks to Parantapa Bhattacharya for catch & patch. * :bug:`102 major` Forego random padding for packets when running under - ``*-ctr`` ciphers. This corrects some slowdowns on platforms where random byte - generation is inefficient (e.g. Windows). Thanks to ``@warthog618` for catch - & patch, and Michael van der Kolff for code/technique review. + ``*-ctr`` ciphers. This corrects some slowdowns on platforms where random + byte generation is inefficient (e.g. Windows). Thanks to ``@warthog618`` for + catch & patch, and Michael van der Kolff for code/technique review. * :feature:`127` Turn ``SFTPFile`` into a context manager. Thanks to Michael Williamson for the patch. * :feature:`116` Limit ``Message.get_bytes`` to an upper bound of 1MB to protect -- cgit v1.2.3 From 176493823c4a580bbfd602a19e3fee5d84c5e080 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Wed, 29 Jan 2014 15:16:04 -0800 Subject: Missed a spot w/ SnR --- sites/www/changelog.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'sites') diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst index 71344613..eaf380da 100644 --- a/sites/www/changelog.rst +++ b/sites/www/changelog.rst @@ -54,9 +54,9 @@ Changelog * :feature:`128` Defer FQDN resolution until needed, when parsing SSH config files. Thanks to Parantapa Bhattacharya for catch & patch. * :bug:`102 major` Forego random padding for packets when running under - ``*-ctr`` ciphers. This corrects some slowdowns on platforms where random byte - generation is inefficient (e.g. Windows). Thanks to ``@warthog618` for catch - & patch, and Michael van der Kolff for code/technique review. + ``*-ctr`` ciphers. This corrects some slowdowns on platforms where random + byte generation is inefficient (e.g. Windows). Thanks to ``@warthog618`` for + catch & patch, and Michael van der Kolff for code/technique review. * :feature:`127` Turn ``SFTPFile`` into a context manager. Thanks to Michael Williamson for the patch. * :feature:`116` Limit ``Message.get_bytes`` to an upper bound of 1MB to protect -- cgit v1.2.3 From d0d711ac788ace57186d09765c173f8c6679198e Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Wed, 29 Jan 2014 15:20:49 -0800 Subject: Port 1.11.1 --- sites/www/changelog.rst | 1 + 1 file changed, 1 insertion(+) (limited to 'sites') diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst index 741374ce..31359c2d 100644 --- a/sites/www/changelog.rst +++ b/sites/www/changelog.rst @@ -18,6 +18,7 @@ Changelog Buchanan for catch & Dave Foster for patch. * :bug:`199` Typo fix in the license header cross-project. Thanks to Armin Ronacher for catch & patch. +* :release:`1.11.1 <2013-09-20>` * :release:`1.10.3 <2013-09-20>` * :bug:`162` Clean up HMAC module import to avoid deadlocks in certain uses of SSHClient. Thanks to Gernot Hillier for the catch & suggested fix. -- cgit v1.2.3 From a83f0d3038e8d16e7c160293d16c2736645564d6 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Thu, 30 Jan 2014 10:40:29 -0800 Subject: Add rest of 1.11 releases --- sites/www/changelog.rst | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) (limited to 'sites') diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst index 31359c2d..ec27dfca 100644 --- a/sites/www/changelog.rst +++ b/sites/www/changelog.rst @@ -2,15 +2,21 @@ Changelog ========= +* :release:`1.11.4 <2014-01-21>` * :release:`1.10.6 <2014-01-21>` * :bug:`193` (and its attentant PRs :issue:`230` & :issue:`253`): Fix SSH agent problems present on Windows. Thanks to David Hobbs for initial report and to Aarni Koskela & Olle Lundberg for the patches. +* :release:`1.11.3 <2014-01-08>` * :release:`1.10.5 <2014-01-08>` * :bug:`176` Fix AttributeError bugs in known_hosts file (re)loading. Thanks to Nathan Scowcroft for the patch & Martin Blumenstingl for the initial test case. -* :release:`1.10.4 <2013-09-27>` +* :release:`1.11.2 <2013-09-27>` +* :release:`1.10.4 <2013-09-27>` 179, 200, 199 +* :bug:`156` Fix potential deadlock condition when using Channel objects as + sockets (e.g. when using SSH gatewaying). Thanks to Steven Noonan and Frank + Arnold for catch & patch. * :bug:`179` Fix a missing variable causing errors when an ssh_config file has a non-default AddressFamily set. Thanks to Ed Marshall & Tomaz Muraus for catch & patch. -- cgit v1.2.3 From 14929d6909e77cbae25e1f2ac92b707a6310df22 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Thu, 30 Jan 2014 10:45:00 -0800 Subject: 1.12 releases --- sites/www/changelog.rst | 21 +++++++++++++++++++-- 1 file changed, 19 insertions(+), 2 deletions(-) (limited to 'sites') diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst index ec27dfca..697bc987 100644 --- a/sites/www/changelog.rst +++ b/sites/www/changelog.rst @@ -2,18 +2,35 @@ Changelog ========= +* :release:`1.12.2 <2014-01-21>` * :release:`1.11.4 <2014-01-21>` * :release:`1.10.6 <2014-01-21>` * :bug:`193` (and its attentant PRs :issue:`230` & :issue:`253`): Fix SSH agent problems present on Windows. Thanks to David Hobbs for initial report and to Aarni Koskela & Olle Lundberg for the patches. -* :release:`1.11.3 <2014-01-08>` -* :release:`1.10.5 <2014-01-08>` +* :release:`1.12.1 <2014-01-08>` +* :release:`1.11.3 <2014-01-08>` 176 +* :release:`1.10.5 <2014-01-08>` 176 +* :bug:`225` Note ecdsa requirement in README. Thanks to Amaury Rodriguez for + the catch. * :bug:`176` Fix AttributeError bugs in known_hosts file (re)loading. Thanks to Nathan Scowcroft for the patch & Martin Blumenstingl for the initial test case. +* :release:`1.12.0 <2013-09-27>` * :release:`1.11.2 <2013-09-27>` * :release:`1.10.4 <2013-09-27>` 179, 200, 199 +* :feature:`152` Add tentative support for ECDSA keys. *This adds the ecdsa + module as a new dependency of Paramiko.* The module is available at + [warner/python-ecdsa on Github](https://github.com/warner/python-ecdsa) and + [ecdsa on PyPI](https://pypi.python.org/pypi/ecdsa). + + * Note that you might still run into problems with key negotiation -- + Paramiko picks the first key that the server offers, which might not be + what you have in your known_hosts file. + * Mega thanks to Ethan Glasser-Camp for the patch. + +* #136: Add server-side support for the SSH protocol's 'env' command. Thanks to + Benjamin Pollack for the patch. * :bug:`156` Fix potential deadlock condition when using Channel objects as sockets (e.g. when using SSH gatewaying). Thanks to Steven Noonan and Frank Arnold for catch & patch. -- cgit v1.2.3 From 5ba3761f21ebdb0082ea16343c88c139063853be Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Thu, 30 Jan 2014 10:55:10 -0800 Subject: Fix some boogs in changelog --- sites/www/changelog.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) (limited to 'sites') diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst index 697bc987..9df85c4b 100644 --- a/sites/www/changelog.rst +++ b/sites/www/changelog.rst @@ -3,8 +3,8 @@ Changelog ========= * :release:`1.12.2 <2014-01-21>` -* :release:`1.11.4 <2014-01-21>` -* :release:`1.10.6 <2014-01-21>` +* :release:`1.11.4 <2014-01-21>` 193 +* :release:`1.10.6 <2014-01-21>` 193 * :bug:`193` (and its attentant PRs :issue:`230` & :issue:`253`): Fix SSH agent problems present on Windows. Thanks to David Hobbs for initial report and to Aarni Koskela & Olle Lundberg for the patches. @@ -18,7 +18,7 @@ Changelog case. * :release:`1.12.0 <2013-09-27>` * :release:`1.11.2 <2013-09-27>` -* :release:`1.10.4 <2013-09-27>` 179, 200, 199 +* :release:`1.10.4 <2013-09-27>` 199, 200, 179 * :feature:`152` Add tentative support for ECDSA keys. *This adds the ecdsa module as a new dependency of Paramiko.* The module is available at [warner/python-ecdsa on Github](https://github.com/warner/python-ecdsa) and @@ -29,8 +29,8 @@ Changelog what you have in your known_hosts file. * Mega thanks to Ethan Glasser-Camp for the patch. -* #136: Add server-side support for the SSH protocol's 'env' command. Thanks to - Benjamin Pollack for the patch. +* :feature:`136` Add server-side support for the SSH protocol's 'env' command. + Thanks to Benjamin Pollack for the patch. * :bug:`156` Fix potential deadlock condition when using Channel objects as sockets (e.g. when using SSH gatewaying). Thanks to Steven Noonan and Frank Arnold for catch & patch. -- cgit v1.2.3 From 70bcde95c1df9858c9e7dbe5310c8bfc0b4b5d5b Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Thu, 30 Jan 2014 10:55:10 -0800 Subject: Backport changelog bugfix from 1.12 --- sites/www/changelog.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'sites') diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst index eaf380da..05392858 100644 --- a/sites/www/changelog.rst +++ b/sites/www/changelog.rst @@ -2,7 +2,7 @@ Changelog ========= -* :release:`1.10.6 <2014-01-21>` +* :release:`1.10.6 <2014-01-21>` 193 * :bug:`193` (and its attentant PRs :issue:`230` & :issue:`253`): Fix SSH agent problems present on Windows. Thanks to David Hobbs for initial report and to Aarni Koskela & Olle Lundberg for the patches. @@ -10,7 +10,7 @@ Changelog * :bug:`176` Fix AttributeError bugs in known_hosts file (re)loading. Thanks to Nathan Scowcroft for the patch & Martin Blumenstingl for the initial test case. -* :release:`1.10.4 <2013-09-27>` +* :release:`1.10.4 <2013-09-27>` 199, 200, 179 * :bug:`179` Fix a missing variable causing errors when an ssh_config file has a non-default AddressFamily set. Thanks to Ed Marshall & Tomaz Muraus for catch & patch. -- cgit v1.2.3 From 343d0492a74e80e915f62c394c76f5b34415025b Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Thu, 30 Jan 2014 10:55:10 -0800 Subject: Backport changelog bugfix from 1.12 --- sites/www/changelog.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'sites') diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst index ec27dfca..6e5f6188 100644 --- a/sites/www/changelog.rst +++ b/sites/www/changelog.rst @@ -2,8 +2,8 @@ Changelog ========= -* :release:`1.11.4 <2014-01-21>` -* :release:`1.10.6 <2014-01-21>` +* :release:`1.11.4 <2014-01-21>` 193 +* :release:`1.10.6 <2014-01-21>` 193 * :bug:`193` (and its attentant PRs :issue:`230` & :issue:`253`): Fix SSH agent problems present on Windows. Thanks to David Hobbs for initial report and to Aarni Koskela & Olle Lundberg for the patches. @@ -13,7 +13,7 @@ Changelog to Nathan Scowcroft for the patch & Martin Blumenstingl for the initial test case. * :release:`1.11.2 <2013-09-27>` -* :release:`1.10.4 <2013-09-27>` 179, 200, 199 +* :release:`1.10.4 <2013-09-27>` 199, 200, 179 * :bug:`156` Fix potential deadlock condition when using Channel objects as sockets (e.g. when using SSH gatewaying). Thanks to Steven Noonan and Frank Arnold for catch & patch. -- cgit v1.2.3 From 52183257d0ac71c72263331c3542d36a2b49ab94 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Thu, 30 Jan 2014 14:20:04 -0800 Subject: Remove blog link for now --- sites/www/contact.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'sites') diff --git a/sites/www/contact.rst b/sites/www/contact.rst index b479f170..2b6583f5 100644 --- a/sites/www/contact.rst +++ b/sites/www/contact.rst @@ -8,4 +8,4 @@ following ways: * IRC: ``#paramiko`` on Freenode * Mailing list: ``paramiko@librelist.com`` (see `the LibreList homepage `_ for usage details). -* This website's :doc:`blog `. +* This website - a blog section is forthcoming. -- cgit v1.2.3 From 55722240b5b676277ef26a20b4b03ef81be3b372 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Thu, 30 Jan 2014 14:20:13 -0800 Subject: Fix broken link format --- sites/www/contributing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'sites') diff --git a/sites/www/contributing.rst b/sites/www/contributing.rst index b121e64b..2b752cc5 100644 --- a/sites/www/contributing.rst +++ b/sites/www/contributing.rst @@ -6,7 +6,7 @@ How to get the code =================== Our primary Git repository is on Github at `paramiko/paramiko -`; please follow their instruction for +`_; please follow their instructions for cloning to your local system. (If you intend to submit patches/pull requests, we recommend forking first, then cloning your fork. Github has excellent documentation for all this.) -- cgit v1.2.3 From 4aa966865393d52ab548ca4b3b12e84260d82f8d Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Thu, 30 Jan 2014 14:31:59 -0800 Subject: Don't preseed releases, ugh --- sites/www/changelog.rst | 1 - 1 file changed, 1 deletion(-) (limited to 'sites') diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst index 05392858..235978d8 100644 --- a/sites/www/changelog.rst +++ b/sites/www/changelog.rst @@ -2,7 +2,6 @@ Changelog ========= -* :release:`1.10.6 <2014-01-21>` 193 * :bug:`193` (and its attentant PRs :issue:`230` & :issue:`253`): Fix SSH agent problems present on Windows. Thanks to David Hobbs for initial report and to Aarni Koskela & Olle Lundberg for the patches. -- cgit v1.2.3 From 0f2fb262870d080d872bb4dd9689d2faf75545ee Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Mon, 3 Feb 2014 14:09:56 -0800 Subject: Update to new Alabaster version for footer/extension stuff --- dev-requirements.txt | 2 +- sites/shared_conf.py | 3 ++- sites/www/conf.py | 2 +- 3 files changed, 4 insertions(+), 3 deletions(-) (limited to 'sites') diff --git a/dev-requirements.txt b/dev-requirements.txt index 2fe1e778..e9770f4f 100644 --- a/dev-requirements.txt +++ b/dev-requirements.txt @@ -3,5 +3,5 @@ invoke>=0.7.0 invocations>=0.4.4 sphinx>=1.1.3 -alabaster>=0.2.0 +alabaster>=0.3.0 releases>=0.2.4 diff --git a/sites/shared_conf.py b/sites/shared_conf.py index 2b98654f..ca555ca5 100644 --- a/sites/shared_conf.py +++ b/sites/shared_conf.py @@ -5,8 +5,9 @@ import sys import alabaster -# Alabaster theme +# Alabaster theme + mini-extension html_theme_path = [alabaster.get_path()] +extensions = ['alabaster'] # Paths relative to invoking conf.py - not this shared file html_static_path = ['../_shared_static'] html_theme = 'alabaster' diff --git a/sites/www/conf.py b/sites/www/conf.py index 1f11c1e2..481acdff 100644 --- a/sites/www/conf.py +++ b/sites/www/conf.py @@ -8,7 +8,7 @@ from shared_conf import * # Local blog extension sys.path.append(abspath('.')) -extensions = ['blog'] +extensions.append('blog') rss_link = 'http://paramiko.org' rss_description = 'Paramiko project news' -- cgit v1.2.3 From cdf62655cbddbc68b42f58984eb60906a253cca0 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Mon, 3 Feb 2014 14:10:23 -0800 Subject: Simplify www page footer. Robey copyright remains in source code but this site is brand new & the footer was real noisy. Eh. --- sites/shared_conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'sites') diff --git a/sites/shared_conf.py b/sites/shared_conf.py index ca555ca5..86ecdfe8 100644 --- a/sites/shared_conf.py +++ b/sites/shared_conf.py @@ -33,7 +33,7 @@ html_sidebars = { # Regular settings project = u'Paramiko' year = datetime.now().year -copyright = u'2013-%d Jeff Forcier, 2003-2012 Robey Pointer' % year +copyright = u'%d Jeff Forcier' % year master_doc = 'index' templates_path = ['_templates'] exclude_trees = ['_build'] -- cgit v1.2.3 From fe3d3beca4985d7c99a306a269cdbd76091ead6a Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Mon, 10 Feb 2014 17:59:25 -0800 Subject: Fix extra colon in changelog --- sites/www/changelog.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'sites') diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst index 235978d8..2378b992 100644 --- a/sites/www/changelog.rst +++ b/sites/www/changelog.rst @@ -2,7 +2,7 @@ Changelog ========= -* :bug:`193` (and its attentant PRs :issue:`230` & :issue:`253`): Fix SSH agent +* :bug:`193` (and its attentant PRs :issue:`230` & :issue:`253`) Fix SSH agent problems present on Windows. Thanks to David Hobbs for initial report and to Aarni Koskela & Olle Lundberg for the patches. * :release:`1.10.5 <2014-01-08>` -- cgit v1.2.3 From 0a2887a8cca93eb5278ff79ed4b014e0ea24c53c Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Mon, 10 Feb 2014 17:59:32 -0800 Subject: Changelog re #35 --- sites/www/changelog.rst | 3 +++ 1 file changed, 3 insertions(+) (limited to 'sites') diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst index 2378b992..1a827587 100644 --- a/sites/www/changelog.rst +++ b/sites/www/changelog.rst @@ -2,6 +2,9 @@ Changelog ========= +* :bug:`34` (PR :issue:`35`) Fix SFTP prefetching incompatibility with some + SFTP servers regarding request/response ordering. Thanks to Richard + Kettlewell for catch & patch. * :bug:`193` (and its attentant PRs :issue:`230` & :issue:`253`) Fix SSH agent problems present on Windows. Thanks to David Hobbs for initial report and to Aarni Koskela & Olle Lundberg for the patches. -- cgit v1.2.3 From c1424546219a769540fc70c54f268e284c0b2b85 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Tue, 11 Feb 2014 14:23:15 -0800 Subject: Start reverting explicit-release stuff in favor of release-line specifiers on bugs. --- dev-requirements.txt | 2 +- sites/www/changelog.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) (limited to 'sites') diff --git a/dev-requirements.txt b/dev-requirements.txt index e9770f4f..6c242c05 100644 --- a/dev-requirements.txt +++ b/dev-requirements.txt @@ -4,4 +4,4 @@ invoke>=0.7.0 invocations>=0.4.4 sphinx>=1.1.3 alabaster>=0.3.0 -releases>=0.2.4 +releases>=0.5.0 diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst index 1a827587..af4c69e4 100644 --- a/sites/www/changelog.rst +++ b/sites/www/changelog.rst @@ -12,7 +12,7 @@ Changelog * :bug:`176` Fix AttributeError bugs in known_hosts file (re)loading. Thanks to Nathan Scowcroft for the patch & Martin Blumenstingl for the initial test case. -* :release:`1.10.4 <2013-09-27>` 199, 200, 179 +* :release:`1.10.4 <2013-09-27>` * :bug:`179` Fix a missing variable causing errors when an ssh_config file has a non-default AddressFamily set. Thanks to Ed Marshall & Tomaz Muraus for catch & patch. -- cgit v1.2.3 From c73616b5b34e10fa40dede6b93f98c212869b056 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Tue, 11 Feb 2014 15:10:39 -0800 Subject: Changelog re #58 --- sites/www/changelog.rst | 2 ++ 1 file changed, 2 insertions(+) (limited to 'sites') diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst index af4c69e4..7247eb76 100644 --- a/sites/www/changelog.rst +++ b/sites/www/changelog.rst @@ -2,6 +2,8 @@ Changelog ========= +* :feature:`58` Allow client code to access the stored SSH server banner via + ``Transport.get_banner()``. Thanks to ``@Jhoanor`` for the patch. * :bug:`34` (PR :issue:`35`) Fix SFTP prefetching incompatibility with some SFTP servers regarding request/response ordering. Thanks to Richard Kettlewell for catch & patch. -- cgit v1.2.3 From 0c493541ebc817d187c87a4a7cf81a8e90c72f5c Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Thu, 13 Feb 2014 09:40:53 -0800 Subject: Changelog re #268 --- sites/www/changelog.rst | 2 ++ 1 file changed, 2 insertions(+) (limited to 'sites') diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst index 1c533f95..2c479b6f 100644 --- a/sites/www/changelog.rst +++ b/sites/www/changelog.rst @@ -2,6 +2,8 @@ Changelog ========= +* :bug:`268` Fix some missed renames of `ProxyCommand` related error classes. + Thanks to Marius Gedminas for catch & patch. * :bug:`34` (PR :issue:`35`) Fix SFTP prefetching incompatibility with some SFTP servers regarding request/response ordering. Thanks to Richard Kettlewell for catch & patch. -- cgit v1.2.3 From c3eb903ed35a2ddd3387d495e844efb2d536cc01 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Thu, 13 Feb 2014 09:48:58 -0800 Subject: Preliminary changelog entry re #252 --- sites/www/changelog.rst | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'sites') diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst index 2c479b6f..08a459cc 100644 --- a/sites/www/changelog.rst +++ b/sites/www/changelog.rst @@ -2,6 +2,11 @@ Changelog ========= +* :bug:`252` (`Fabric #1020 `_) + Tried enhancing the implementation of `ProxyCommand` to avoid a deadlock/hang + condition that frequently occurs at `Transport` shutdown time. Thanks to + Mateusz Kobos, Matthijs van der Vleuten and Guillaume Zitta for the original + reports and to Marius Gedminas for helping test nontrivial test cases. * :bug:`268` Fix some missed renames of `ProxyCommand` related error classes. Thanks to Marius Gedminas for catch & patch. * :bug:`34` (PR :issue:`35`) Fix SFTP prefetching incompatibility with some -- cgit v1.2.3 From 8003c738ca3ea567bfec876bcbf3e7c6facae6a6 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Thu, 13 Feb 2014 09:50:05 -0800 Subject: I hate you sometimes, ReST --- sites/www/changelog.rst | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) (limited to 'sites') diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst index 08a459cc..5034641a 100644 --- a/sites/www/changelog.rst +++ b/sites/www/changelog.rst @@ -3,11 +3,12 @@ Changelog ========= * :bug:`252` (`Fabric #1020 `_) - Tried enhancing the implementation of `ProxyCommand` to avoid a deadlock/hang - condition that frequently occurs at `Transport` shutdown time. Thanks to - Mateusz Kobos, Matthijs van der Vleuten and Guillaume Zitta for the original - reports and to Marius Gedminas for helping test nontrivial test cases. -* :bug:`268` Fix some missed renames of `ProxyCommand` related error classes. + Tried enhancing the implementation of ``ProxyCommand`` to avoid a + deadlock/hang condition that frequently occurs at ``Transport`` shutdown + time. Thanks to Mateusz Kobos, Matthijs van der Vleuten and Guillaume Zitta + for the original reports and to Marius Gedminas for helping test nontrivial + test cases. +* :bug:`268` Fix some missed renames of ``ProxyCommand`` related error classes. Thanks to Marius Gedminas for catch & patch. * :bug:`34` (PR :issue:`35`) Fix SFTP prefetching incompatibility with some SFTP servers regarding request/response ordering. Thanks to Richard -- cgit v1.2.3 From e3a16fac5af103c48ee64034cfca36f6c8c1dfd1 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Thu, 13 Feb 2014 13:48:21 -0800 Subject: Braino in changelog text --- sites/www/changelog.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'sites') diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst index 5034641a..451d695f 100644 --- a/sites/www/changelog.rst +++ b/sites/www/changelog.rst @@ -7,7 +7,7 @@ Changelog deadlock/hang condition that frequently occurs at ``Transport`` shutdown time. Thanks to Mateusz Kobos, Matthijs van der Vleuten and Guillaume Zitta for the original reports and to Marius Gedminas for helping test nontrivial - test cases. + use cases. * :bug:`268` Fix some missed renames of ``ProxyCommand`` related error classes. Thanks to Marius Gedminas for catch & patch. * :bug:`34` (PR :issue:`35`) Fix SFTP prefetching incompatibility with some -- cgit v1.2.3 From fb772a8695a95df3aa1cd3dd45aa6c42302e8640 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Fri, 14 Feb 2014 09:16:35 -0800 Subject: Tweak changelog language --- sites/www/changelog.rst | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) (limited to 'sites') diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst index 451d695f..2faa9641 100644 --- a/sites/www/changelog.rst +++ b/sites/www/changelog.rst @@ -3,11 +3,10 @@ Changelog ========= * :bug:`252` (`Fabric #1020 `_) - Tried enhancing the implementation of ``ProxyCommand`` to avoid a - deadlock/hang condition that frequently occurs at ``Transport`` shutdown - time. Thanks to Mateusz Kobos, Matthijs van der Vleuten and Guillaume Zitta - for the original reports and to Marius Gedminas for helping test nontrivial - use cases. + Enhanced the implementation of ``ProxyCommand`` to avoid a deadlock/hang + condition that frequently occurs at ``Transport`` shutdown time. Thanks to + Mateusz Kobos, Matthijs van der Vleuten and Guillaume Zitta for the original + reports and to Marius Gedminas for helping test nontrivial use cases. * :bug:`268` Fix some missed renames of ``ProxyCommand`` related error classes. Thanks to Marius Gedminas for catch & patch. * :bug:`34` (PR :issue:`35`) Fix SFTP prefetching incompatibility with some -- cgit v1.2.3 From 6d4b37a17f623c2f28c7e372402ab9c8750db95d Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Fri, 14 Feb 2014 09:32:05 -0800 Subject: Catch & patch trimming --- sites/www/changelog.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'sites') diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst index 2faa9641..960adbcb 100644 --- a/sites/www/changelog.rst +++ b/sites/www/changelog.rst @@ -11,7 +11,7 @@ Changelog Thanks to Marius Gedminas for catch & patch. * :bug:`34` (PR :issue:`35`) Fix SFTP prefetching incompatibility with some SFTP servers regarding request/response ordering. Thanks to Richard - Kettlewell for catch & patch. + Kettlewell. * :bug:`193` (and its attentant PRs :issue:`230` & :issue:`253`) Fix SSH agent problems present on Windows. Thanks to David Hobbs for initial report and to Aarni Koskela & Olle Lundberg for the patches. -- cgit v1.2.3 From 457a34f55b1d69c3f7699b3bc055f6c6d90371cd Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Fri, 14 Feb 2014 09:36:33 -0800 Subject: Cut 1.10.6 --- paramiko/__init__.py | 2 +- setup.py | 2 +- sites/www/changelog.rst | 1 + 3 files changed, 3 insertions(+), 2 deletions(-) (limited to 'sites') diff --git a/paramiko/__init__.py b/paramiko/__init__.py index 924e8bb5..7f60b1fa 100644 --- a/paramiko/__init__.py +++ b/paramiko/__init__.py @@ -55,7 +55,7 @@ if sys.version_info < (2, 5): __author__ = "Jeff Forcier " -__version__ = "1.10.5" +__version__ = "1.10.6" __version_info__ = tuple([ int(d) for d in __version__.split(".") ]) __license__ = "GNU Lesser General Public License (LGPL)" diff --git a/setup.py b/setup.py index 8ec4a0ea..bc5f9e6d 100644 --- a/setup.py +++ b/setup.py @@ -52,7 +52,7 @@ if sys.platform == 'darwin': setup(name = "paramiko", - version = "1.10.5", + version = "1.10.6", description = "SSH2 protocol library", author = "Jeff Forcier", author_email = "jeff@bitprophet.org", diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst index af4c69e4..c26b996c 100644 --- a/sites/www/changelog.rst +++ b/sites/www/changelog.rst @@ -2,6 +2,7 @@ Changelog ========= +* :release:`1.10.6 <2014-02-14>` * :bug:`34` (PR :issue:`35`) Fix SFTP prefetching incompatibility with some SFTP servers regarding request/response ordering. Thanks to Richard Kettlewell for catch & patch. -- cgit v1.2.3 From 4a5f007c029cfabac35161d8147d616c79009bd8 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Fri, 14 Feb 2014 09:38:14 -0800 Subject: Cut 1.11.4 --- paramiko/__init__.py | 2 +- setup.py | 2 +- sites/www/changelog.rst | 1 + 3 files changed, 3 insertions(+), 2 deletions(-) (limited to 'sites') diff --git a/paramiko/__init__.py b/paramiko/__init__.py index de89e08d..eba9f608 100644 --- a/paramiko/__init__.py +++ b/paramiko/__init__.py @@ -57,7 +57,7 @@ if sys.version_info < (2, 5): __author__ = "Jeff Forcier " -__version__ = "1.11.3" +__version__ = "1.11.4" __version_info__ = tuple([ int(d) for d in __version__.split(".") ]) __license__ = "GNU Lesser General Public License (LGPL)" diff --git a/setup.py b/setup.py index 33075002..e6ae2dda 100644 --- a/setup.py +++ b/setup.py @@ -52,7 +52,7 @@ if sys.platform == 'darwin': setup(name = "paramiko", - version = "1.11.3", + version = "1.11.4", description = "SSH2 protocol library", author = "Jeff Forcier", author_email = "jeff@bitprophet.org", diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst index 543f41eb..efd6610b 100644 --- a/sites/www/changelog.rst +++ b/sites/www/changelog.rst @@ -2,6 +2,7 @@ Changelog ========= +* :release:`1.11.4 <2014-02-14>` * :release:`1.10.6 <2014-02-14>` * :bug:`252` (`Fabric #1020 `_) Enhanced the implementation of ``ProxyCommand`` to avoid a deadlock/hang -- cgit v1.2.3 From fb786bea9cff8fba3c6852d216dbbcbafbbb524f Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Fri, 14 Feb 2014 09:39:11 -0800 Subject: Cut 1.12.2 --- paramiko/__init__.py | 2 +- setup.py | 2 +- sites/www/changelog.rst | 1 + 3 files changed, 3 insertions(+), 2 deletions(-) (limited to 'sites') diff --git a/paramiko/__init__.py b/paramiko/__init__.py index c996302a..648b595e 100644 --- a/paramiko/__init__.py +++ b/paramiko/__init__.py @@ -57,7 +57,7 @@ if sys.version_info < (2, 5): __author__ = "Jeff Forcier " -__version__ = "1.12.1" +__version__ = "1.12.2" __version_info__ = tuple([ int(d) for d in __version__.split(".") ]) __license__ = "GNU Lesser General Public License (LGPL)" diff --git a/setup.py b/setup.py index f50cfd23..7d6706ed 100644 --- a/setup.py +++ b/setup.py @@ -54,7 +54,7 @@ if sys.platform == 'darwin': setup(name = "paramiko", - version = "1.12.1", + version = "1.12.2", description = "SSH2 protocol library", author = "Jeff Forcier", author_email = "jeff@bitprophet.org", diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst index f9906170..ffacf6e9 100644 --- a/sites/www/changelog.rst +++ b/sites/www/changelog.rst @@ -2,6 +2,7 @@ Changelog ========= +* :release:`1.12.2 <2014-02-14>` * :release:`1.11.4 <2014-02-14>` * :release:`1.10.6 <2014-02-14>` * :bug:`252` (`Fabric #1020 `_) -- cgit v1.2.3 From 30518280f1356465f0acfdb4816843b61303a633 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Fri, 14 Feb 2014 11:53:42 -0800 Subject: Changelog re hash comparison bugfix --- sites/www/changelog.rst | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'sites') diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst index c26b996c..fa58c5f6 100644 --- a/sites/www/changelog.rst +++ b/sites/www/changelog.rst @@ -2,6 +2,10 @@ Changelog ========= +* :bug:`-` Use constant-time hash comparison operations where possible, to + protect against `timing-based attacks + `_. Thanks to Alex Gaynor + for the patch. * :release:`1.10.6 <2014-02-14>` * :bug:`34` (PR :issue:`35`) Fix SFTP prefetching incompatibility with some SFTP servers regarding request/response ordering. Thanks to Richard -- cgit v1.2.3 From b140b29d542e9a0ee1d5c013e3612b8a16ca851b Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Fri, 14 Feb 2014 12:09:59 -0800 Subject: Hook API doc into index/toctree --- sites/docs/index.rst | 3 +++ 1 file changed, 3 insertions(+) (limited to 'sites') diff --git a/sites/docs/index.rst b/sites/docs/index.rst index 08b34320..7ec5825e 100644 --- a/sites/docs/index.rst +++ b/sites/docs/index.rst @@ -4,3 +4,6 @@ Welcome to Paramiko's documentation! This site covers Paramiko's usage & API documentation. For basic info on what Paramiko is, including its public changelog & how the project is maintained, please see `the main website `_. + +.. toctree:: + api -- cgit v1.2.3 From 2346f1a1e937f39343c2805d098b52f6c87f8fc9 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Fri, 14 Feb 2014 13:33:22 -0800 Subject: Swap out all-in-one file with sphinx-apidoc generated stuff --- sites/docs/api.rst | 8 -------- sites/docs/api/agent.rst | 7 +++++++ sites/docs/api/auth_handler.rst | 7 +++++++ sites/docs/api/ber.rst | 7 +++++++ sites/docs/api/buffered_pipe.rst | 7 +++++++ sites/docs/api/channel.rst | 7 +++++++ sites/docs/api/client.rst | 7 +++++++ sites/docs/api/common.rst | 7 +++++++ sites/docs/api/compress.rst | 7 +++++++ sites/docs/api/config.rst | 7 +++++++ sites/docs/api/dsskey.rst | 7 +++++++ sites/docs/api/file.rst | 7 +++++++ sites/docs/api/hostkeys.rst | 7 +++++++ sites/docs/api/kex_gex.rst | 7 +++++++ sites/docs/api/kex_group1.rst | 7 +++++++ sites/docs/api/logging22.rst | 7 +++++++ sites/docs/api/message.rst | 7 +++++++ sites/docs/api/packet.rst | 7 +++++++ sites/docs/api/pipe.rst | 7 +++++++ sites/docs/api/pkey.rst | 7 +++++++ sites/docs/api/primes.rst | 7 +++++++ sites/docs/api/proxy.rst | 7 +++++++ sites/docs/api/resource.rst | 7 +++++++ sites/docs/api/rsakey.rst | 7 +++++++ sites/docs/api/server.rst | 7 +++++++ sites/docs/api/sftp.rst | 7 +++++++ sites/docs/api/sftp_attr.rst | 7 +++++++ sites/docs/api/sftp_client.rst | 7 +++++++ sites/docs/api/sftp_file.rst | 7 +++++++ sites/docs/api/sftp_handle.rst | 7 +++++++ sites/docs/api/sftp_server.rst | 7 +++++++ sites/docs/api/sftp_si.rst | 7 +++++++ sites/docs/api/ssh_exception.rst | 7 +++++++ sites/docs/api/transport.rst | 7 +++++++ sites/docs/api/util.rst | 7 +++++++ sites/docs/api/win_pageant.rst | 7 +++++++ sites/docs/index.rst | 4 +++- 37 files changed, 248 insertions(+), 9 deletions(-) delete mode 100644 sites/docs/api.rst create mode 100644 sites/docs/api/agent.rst create mode 100644 sites/docs/api/auth_handler.rst create mode 100644 sites/docs/api/ber.rst create mode 100644 sites/docs/api/buffered_pipe.rst create mode 100644 sites/docs/api/channel.rst create mode 100644 sites/docs/api/client.rst create mode 100644 sites/docs/api/common.rst create mode 100644 sites/docs/api/compress.rst create mode 100644 sites/docs/api/config.rst create mode 100644 sites/docs/api/dsskey.rst create mode 100644 sites/docs/api/file.rst create mode 100644 sites/docs/api/hostkeys.rst create mode 100644 sites/docs/api/kex_gex.rst create mode 100644 sites/docs/api/kex_group1.rst create mode 100644 sites/docs/api/logging22.rst create mode 100644 sites/docs/api/message.rst create mode 100644 sites/docs/api/packet.rst create mode 100644 sites/docs/api/pipe.rst create mode 100644 sites/docs/api/pkey.rst create mode 100644 sites/docs/api/primes.rst create mode 100644 sites/docs/api/proxy.rst create mode 100644 sites/docs/api/resource.rst create mode 100644 sites/docs/api/rsakey.rst create mode 100644 sites/docs/api/server.rst create mode 100644 sites/docs/api/sftp.rst create mode 100644 sites/docs/api/sftp_attr.rst create mode 100644 sites/docs/api/sftp_client.rst create mode 100644 sites/docs/api/sftp_file.rst create mode 100644 sites/docs/api/sftp_handle.rst create mode 100644 sites/docs/api/sftp_server.rst create mode 100644 sites/docs/api/sftp_si.rst create mode 100644 sites/docs/api/ssh_exception.rst create mode 100644 sites/docs/api/transport.rst create mode 100644 sites/docs/api/util.rst create mode 100644 sites/docs/api/win_pageant.rst (limited to 'sites') diff --git a/sites/docs/api.rst b/sites/docs/api.rst deleted file mode 100644 index 47615709..00000000 --- a/sites/docs/api.rst +++ /dev/null @@ -1,8 +0,0 @@ -.. _api: - -API -=== - -.. automodule:: paramiko - :members: - :special-members: diff --git a/sites/docs/api/agent.rst b/sites/docs/api/agent.rst new file mode 100644 index 00000000..cb966f2b --- /dev/null +++ b/sites/docs/api/agent.rst @@ -0,0 +1,7 @@ +paramiko.agent module +===================== + +.. automodule:: paramiko.agent + :members: + :undoc-members: + :show-inheritance: diff --git a/sites/docs/api/auth_handler.rst b/sites/docs/api/auth_handler.rst new file mode 100644 index 00000000..c35f5b66 --- /dev/null +++ b/sites/docs/api/auth_handler.rst @@ -0,0 +1,7 @@ +paramiko.auth_handler module +============================ + +.. automodule:: paramiko.auth_handler + :members: + :undoc-members: + :show-inheritance: diff --git a/sites/docs/api/ber.rst b/sites/docs/api/ber.rst new file mode 100644 index 00000000..3627528f --- /dev/null +++ b/sites/docs/api/ber.rst @@ -0,0 +1,7 @@ +paramiko.ber module +=================== + +.. automodule:: paramiko.ber + :members: + :undoc-members: + :show-inheritance: diff --git a/sites/docs/api/buffered_pipe.rst b/sites/docs/api/buffered_pipe.rst new file mode 100644 index 00000000..57411fc7 --- /dev/null +++ b/sites/docs/api/buffered_pipe.rst @@ -0,0 +1,7 @@ +paramiko.buffered_pipe module +============================= + +.. automodule:: paramiko.buffered_pipe + :members: + :undoc-members: + :show-inheritance: diff --git a/sites/docs/api/channel.rst b/sites/docs/api/channel.rst new file mode 100644 index 00000000..85848484 --- /dev/null +++ b/sites/docs/api/channel.rst @@ -0,0 +1,7 @@ +paramiko.channel module +======================= + +.. automodule:: paramiko.channel + :members: + :undoc-members: + :show-inheritance: diff --git a/sites/docs/api/client.rst b/sites/docs/api/client.rst new file mode 100644 index 00000000..50171371 --- /dev/null +++ b/sites/docs/api/client.rst @@ -0,0 +1,7 @@ +paramiko.client module +====================== + +.. automodule:: paramiko.client + :members: + :undoc-members: + :show-inheritance: diff --git a/sites/docs/api/common.rst b/sites/docs/api/common.rst new file mode 100644 index 00000000..0abcf986 --- /dev/null +++ b/sites/docs/api/common.rst @@ -0,0 +1,7 @@ +paramiko.common module +====================== + +.. automodule:: paramiko.common + :members: + :undoc-members: + :show-inheritance: diff --git a/sites/docs/api/compress.rst b/sites/docs/api/compress.rst new file mode 100644 index 00000000..9089efbd --- /dev/null +++ b/sites/docs/api/compress.rst @@ -0,0 +1,7 @@ +paramiko.compress module +======================== + +.. automodule:: paramiko.compress + :members: + :undoc-members: + :show-inheritance: diff --git a/sites/docs/api/config.rst b/sites/docs/api/config.rst new file mode 100644 index 00000000..fb587953 --- /dev/null +++ b/sites/docs/api/config.rst @@ -0,0 +1,7 @@ +paramiko.config module +====================== + +.. automodule:: paramiko.config + :members: + :undoc-members: + :show-inheritance: diff --git a/sites/docs/api/dsskey.rst b/sites/docs/api/dsskey.rst new file mode 100644 index 00000000..67fbd84e --- /dev/null +++ b/sites/docs/api/dsskey.rst @@ -0,0 +1,7 @@ +paramiko.dsskey module +====================== + +.. automodule:: paramiko.dsskey + :members: + :undoc-members: + :show-inheritance: diff --git a/sites/docs/api/file.rst b/sites/docs/api/file.rst new file mode 100644 index 00000000..044ceab0 --- /dev/null +++ b/sites/docs/api/file.rst @@ -0,0 +1,7 @@ +paramiko.file module +==================== + +.. automodule:: paramiko.file + :members: + :undoc-members: + :show-inheritance: diff --git a/sites/docs/api/hostkeys.rst b/sites/docs/api/hostkeys.rst new file mode 100644 index 00000000..0428fa92 --- /dev/null +++ b/sites/docs/api/hostkeys.rst @@ -0,0 +1,7 @@ +paramiko.hostkeys module +======================== + +.. automodule:: paramiko.hostkeys + :members: + :undoc-members: + :show-inheritance: diff --git a/sites/docs/api/kex_gex.rst b/sites/docs/api/kex_gex.rst new file mode 100644 index 00000000..749853b3 --- /dev/null +++ b/sites/docs/api/kex_gex.rst @@ -0,0 +1,7 @@ +paramiko.kex_gex module +======================= + +.. automodule:: paramiko.kex_gex + :members: + :undoc-members: + :show-inheritance: diff --git a/sites/docs/api/kex_group1.rst b/sites/docs/api/kex_group1.rst new file mode 100644 index 00000000..8bef58d0 --- /dev/null +++ b/sites/docs/api/kex_group1.rst @@ -0,0 +1,7 @@ +paramiko.kex_group1 module +========================== + +.. automodule:: paramiko.kex_group1 + :members: + :undoc-members: + :show-inheritance: diff --git a/sites/docs/api/logging22.rst b/sites/docs/api/logging22.rst new file mode 100644 index 00000000..55c17882 --- /dev/null +++ b/sites/docs/api/logging22.rst @@ -0,0 +1,7 @@ +paramiko.logging22 module +========================= + +.. automodule:: paramiko.logging22 + :members: + :undoc-members: + :show-inheritance: diff --git a/sites/docs/api/message.rst b/sites/docs/api/message.rst new file mode 100644 index 00000000..4f7b5838 --- /dev/null +++ b/sites/docs/api/message.rst @@ -0,0 +1,7 @@ +paramiko.message module +======================= + +.. automodule:: paramiko.message + :members: + :undoc-members: + :show-inheritance: diff --git a/sites/docs/api/packet.rst b/sites/docs/api/packet.rst new file mode 100644 index 00000000..6a127d7a --- /dev/null +++ b/sites/docs/api/packet.rst @@ -0,0 +1,7 @@ +paramiko.packet module +====================== + +.. automodule:: paramiko.packet + :members: + :undoc-members: + :show-inheritance: diff --git a/sites/docs/api/pipe.rst b/sites/docs/api/pipe.rst new file mode 100644 index 00000000..5ec75fa5 --- /dev/null +++ b/sites/docs/api/pipe.rst @@ -0,0 +1,7 @@ +paramiko.pipe module +==================== + +.. automodule:: paramiko.pipe + :members: + :undoc-members: + :show-inheritance: diff --git a/sites/docs/api/pkey.rst b/sites/docs/api/pkey.rst new file mode 100644 index 00000000..fb75e664 --- /dev/null +++ b/sites/docs/api/pkey.rst @@ -0,0 +1,7 @@ +paramiko.pkey module +==================== + +.. automodule:: paramiko.pkey + :members: + :undoc-members: + :show-inheritance: diff --git a/sites/docs/api/primes.rst b/sites/docs/api/primes.rst new file mode 100644 index 00000000..8dfe2a47 --- /dev/null +++ b/sites/docs/api/primes.rst @@ -0,0 +1,7 @@ +paramiko.primes module +====================== + +.. automodule:: paramiko.primes + :members: + :undoc-members: + :show-inheritance: diff --git a/sites/docs/api/proxy.rst b/sites/docs/api/proxy.rst new file mode 100644 index 00000000..5a0f5aff --- /dev/null +++ b/sites/docs/api/proxy.rst @@ -0,0 +1,7 @@ +paramiko.proxy module +===================== + +.. automodule:: paramiko.proxy + :members: + :undoc-members: + :show-inheritance: diff --git a/sites/docs/api/resource.rst b/sites/docs/api/resource.rst new file mode 100644 index 00000000..a4527ab1 --- /dev/null +++ b/sites/docs/api/resource.rst @@ -0,0 +1,7 @@ +paramiko.resource module +======================== + +.. automodule:: paramiko.resource + :members: + :undoc-members: + :show-inheritance: diff --git a/sites/docs/api/rsakey.rst b/sites/docs/api/rsakey.rst new file mode 100644 index 00000000..7ad995ce --- /dev/null +++ b/sites/docs/api/rsakey.rst @@ -0,0 +1,7 @@ +paramiko.rsakey module +====================== + +.. automodule:: paramiko.rsakey + :members: + :undoc-members: + :show-inheritance: diff --git a/sites/docs/api/server.rst b/sites/docs/api/server.rst new file mode 100644 index 00000000..3821c9be --- /dev/null +++ b/sites/docs/api/server.rst @@ -0,0 +1,7 @@ +paramiko.server module +====================== + +.. automodule:: paramiko.server + :members: + :undoc-members: + :show-inheritance: diff --git a/sites/docs/api/sftp.rst b/sites/docs/api/sftp.rst new file mode 100644 index 00000000..1d65900a --- /dev/null +++ b/sites/docs/api/sftp.rst @@ -0,0 +1,7 @@ +paramiko.sftp module +==================== + +.. automodule:: paramiko.sftp + :members: + :undoc-members: + :show-inheritance: diff --git a/sites/docs/api/sftp_attr.rst b/sites/docs/api/sftp_attr.rst new file mode 100644 index 00000000..114748c6 --- /dev/null +++ b/sites/docs/api/sftp_attr.rst @@ -0,0 +1,7 @@ +paramiko.sftp_attr module +========================= + +.. automodule:: paramiko.sftp_attr + :members: + :undoc-members: + :show-inheritance: diff --git a/sites/docs/api/sftp_client.rst b/sites/docs/api/sftp_client.rst new file mode 100644 index 00000000..ee973df2 --- /dev/null +++ b/sites/docs/api/sftp_client.rst @@ -0,0 +1,7 @@ +paramiko.sftp_client module +=========================== + +.. automodule:: paramiko.sftp_client + :members: + :undoc-members: + :show-inheritance: diff --git a/sites/docs/api/sftp_file.rst b/sites/docs/api/sftp_file.rst new file mode 100644 index 00000000..77756807 --- /dev/null +++ b/sites/docs/api/sftp_file.rst @@ -0,0 +1,7 @@ +paramiko.sftp_file module +========================= + +.. automodule:: paramiko.sftp_file + :members: + :undoc-members: + :show-inheritance: diff --git a/sites/docs/api/sftp_handle.rst b/sites/docs/api/sftp_handle.rst new file mode 100644 index 00000000..0f563b16 --- /dev/null +++ b/sites/docs/api/sftp_handle.rst @@ -0,0 +1,7 @@ +paramiko.sftp_handle module +=========================== + +.. automodule:: paramiko.sftp_handle + :members: + :undoc-members: + :show-inheritance: diff --git a/sites/docs/api/sftp_server.rst b/sites/docs/api/sftp_server.rst new file mode 100644 index 00000000..50e84b18 --- /dev/null +++ b/sites/docs/api/sftp_server.rst @@ -0,0 +1,7 @@ +paramiko.sftp_server module +=========================== + +.. automodule:: paramiko.sftp_server + :members: + :undoc-members: + :show-inheritance: diff --git a/sites/docs/api/sftp_si.rst b/sites/docs/api/sftp_si.rst new file mode 100644 index 00000000..e369d879 --- /dev/null +++ b/sites/docs/api/sftp_si.rst @@ -0,0 +1,7 @@ +paramiko.sftp_si module +======================= + +.. automodule:: paramiko.sftp_si + :members: + :undoc-members: + :show-inheritance: diff --git a/sites/docs/api/ssh_exception.rst b/sites/docs/api/ssh_exception.rst new file mode 100644 index 00000000..a4b6d2aa --- /dev/null +++ b/sites/docs/api/ssh_exception.rst @@ -0,0 +1,7 @@ +paramiko.ssh_exception module +============================= + +.. automodule:: paramiko.ssh_exception + :members: + :undoc-members: + :show-inheritance: diff --git a/sites/docs/api/transport.rst b/sites/docs/api/transport.rst new file mode 100644 index 00000000..19fb0e88 --- /dev/null +++ b/sites/docs/api/transport.rst @@ -0,0 +1,7 @@ +paramiko.transport module +========================= + +.. automodule:: paramiko.transport + :members: + :undoc-members: + :show-inheritance: diff --git a/sites/docs/api/util.rst b/sites/docs/api/util.rst new file mode 100644 index 00000000..ae3eae0f --- /dev/null +++ b/sites/docs/api/util.rst @@ -0,0 +1,7 @@ +paramiko.util module +==================== + +.. automodule:: paramiko.util + :members: + :undoc-members: + :show-inheritance: diff --git a/sites/docs/api/win_pageant.rst b/sites/docs/api/win_pageant.rst new file mode 100644 index 00000000..561a5143 --- /dev/null +++ b/sites/docs/api/win_pageant.rst @@ -0,0 +1,7 @@ +paramiko.win_pageant module +=========================== + +.. automodule:: paramiko.win_pageant + :members: + :undoc-members: + :show-inheritance: diff --git a/sites/docs/index.rst b/sites/docs/index.rst index 7ec5825e..89c75831 100644 --- a/sites/docs/index.rst +++ b/sites/docs/index.rst @@ -6,4 +6,6 @@ Paramiko is, including its public changelog & how the project is maintained, please see `the main website `_. .. toctree:: - api + :glob: + + api/* -- cgit v1.2.3 From 4a98671bf67c3df92b9b60640480828053cda0eb Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Fri, 14 Feb 2014 13:33:36 -0800 Subject: Tweak conf.py in prep for less boilerplatey versions of module files --- sites/docs/conf.py | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) (limited to 'sites') diff --git a/sites/docs/conf.py b/sites/docs/conf.py index 94267f0a..c0f51f76 100644 --- a/sites/docs/conf.py +++ b/sites/docs/conf.py @@ -4,4 +4,8 @@ sys.path.append(os.path.abspath('..')) sys.path.append(os.path.abspath('../..')) from shared_conf import * -extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx'] +# Enable autodoc, intersphinx +extensions.extend(['sphinx.ext.autodoc', 'sphinx.ext.intersphinx']) + +# Autodoc settings +autodoc_default_flags = ['members', 'special-members'] -- cgit v1.2.3 From 95b5fd22559e3e24e125471a99962601b490b965 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Fri, 14 Feb 2014 15:48:39 -0800 Subject: Remove autodoc boilerplate flags from automodule directives --- sites/docs/api/agent.rst | 3 --- sites/docs/api/auth_handler.rst | 3 --- sites/docs/api/ber.rst | 3 --- sites/docs/api/buffered_pipe.rst | 3 --- sites/docs/api/channel.rst | 3 --- sites/docs/api/client.rst | 3 --- sites/docs/api/common.rst | 3 --- sites/docs/api/compress.rst | 3 --- sites/docs/api/config.rst | 3 --- sites/docs/api/dsskey.rst | 3 --- sites/docs/api/file.rst | 3 --- sites/docs/api/hostkeys.rst | 3 --- sites/docs/api/kex_gex.rst | 3 --- sites/docs/api/kex_group1.rst | 3 --- sites/docs/api/logging22.rst | 3 --- sites/docs/api/message.rst | 3 --- sites/docs/api/packet.rst | 3 --- sites/docs/api/pipe.rst | 3 --- sites/docs/api/pkey.rst | 3 --- sites/docs/api/primes.rst | 3 --- sites/docs/api/proxy.rst | 3 --- sites/docs/api/resource.rst | 3 --- sites/docs/api/rsakey.rst | 3 --- sites/docs/api/server.rst | 3 --- sites/docs/api/sftp.rst | 3 --- sites/docs/api/sftp_attr.rst | 3 --- sites/docs/api/sftp_client.rst | 3 --- sites/docs/api/sftp_file.rst | 3 --- sites/docs/api/sftp_handle.rst | 3 --- sites/docs/api/sftp_server.rst | 3 --- sites/docs/api/sftp_si.rst | 3 --- sites/docs/api/ssh_exception.rst | 3 --- sites/docs/api/transport.rst | 3 --- sites/docs/api/util.rst | 3 --- sites/docs/api/win_pageant.rst | 3 --- 35 files changed, 105 deletions(-) (limited to 'sites') diff --git a/sites/docs/api/agent.rst b/sites/docs/api/agent.rst index cb966f2b..26d9c97a 100644 --- a/sites/docs/api/agent.rst +++ b/sites/docs/api/agent.rst @@ -2,6 +2,3 @@ paramiko.agent module ===================== .. automodule:: paramiko.agent - :members: - :undoc-members: - :show-inheritance: diff --git a/sites/docs/api/auth_handler.rst b/sites/docs/api/auth_handler.rst index c35f5b66..0fdb490f 100644 --- a/sites/docs/api/auth_handler.rst +++ b/sites/docs/api/auth_handler.rst @@ -2,6 +2,3 @@ paramiko.auth_handler module ============================ .. automodule:: paramiko.auth_handler - :members: - :undoc-members: - :show-inheritance: diff --git a/sites/docs/api/ber.rst b/sites/docs/api/ber.rst index 3627528f..20ab604e 100644 --- a/sites/docs/api/ber.rst +++ b/sites/docs/api/ber.rst @@ -2,6 +2,3 @@ paramiko.ber module =================== .. automodule:: paramiko.ber - :members: - :undoc-members: - :show-inheritance: diff --git a/sites/docs/api/buffered_pipe.rst b/sites/docs/api/buffered_pipe.rst index 57411fc7..a8cdb581 100644 --- a/sites/docs/api/buffered_pipe.rst +++ b/sites/docs/api/buffered_pipe.rst @@ -2,6 +2,3 @@ paramiko.buffered_pipe module ============================= .. automodule:: paramiko.buffered_pipe - :members: - :undoc-members: - :show-inheritance: diff --git a/sites/docs/api/channel.rst b/sites/docs/api/channel.rst index 85848484..db8280b5 100644 --- a/sites/docs/api/channel.rst +++ b/sites/docs/api/channel.rst @@ -2,6 +2,3 @@ paramiko.channel module ======================= .. automodule:: paramiko.channel - :members: - :undoc-members: - :show-inheritance: diff --git a/sites/docs/api/client.rst b/sites/docs/api/client.rst index 50171371..840ffec8 100644 --- a/sites/docs/api/client.rst +++ b/sites/docs/api/client.rst @@ -2,6 +2,3 @@ paramiko.client module ====================== .. automodule:: paramiko.client - :members: - :undoc-members: - :show-inheritance: diff --git a/sites/docs/api/common.rst b/sites/docs/api/common.rst index 0abcf986..fb99f218 100644 --- a/sites/docs/api/common.rst +++ b/sites/docs/api/common.rst @@ -2,6 +2,3 @@ paramiko.common module ====================== .. automodule:: paramiko.common - :members: - :undoc-members: - :show-inheritance: diff --git a/sites/docs/api/compress.rst b/sites/docs/api/compress.rst index 9089efbd..93e04231 100644 --- a/sites/docs/api/compress.rst +++ b/sites/docs/api/compress.rst @@ -2,6 +2,3 @@ paramiko.compress module ======================== .. automodule:: paramiko.compress - :members: - :undoc-members: - :show-inheritance: diff --git a/sites/docs/api/config.rst b/sites/docs/api/config.rst index fb587953..dc030b48 100644 --- a/sites/docs/api/config.rst +++ b/sites/docs/api/config.rst @@ -2,6 +2,3 @@ paramiko.config module ====================== .. automodule:: paramiko.config - :members: - :undoc-members: - :show-inheritance: diff --git a/sites/docs/api/dsskey.rst b/sites/docs/api/dsskey.rst index 67fbd84e..c4d8d652 100644 --- a/sites/docs/api/dsskey.rst +++ b/sites/docs/api/dsskey.rst @@ -2,6 +2,3 @@ paramiko.dsskey module ====================== .. automodule:: paramiko.dsskey - :members: - :undoc-members: - :show-inheritance: diff --git a/sites/docs/api/file.rst b/sites/docs/api/file.rst index 044ceab0..d16c834f 100644 --- a/sites/docs/api/file.rst +++ b/sites/docs/api/file.rst @@ -2,6 +2,3 @@ paramiko.file module ==================== .. automodule:: paramiko.file - :members: - :undoc-members: - :show-inheritance: diff --git a/sites/docs/api/hostkeys.rst b/sites/docs/api/hostkeys.rst index 0428fa92..5379a369 100644 --- a/sites/docs/api/hostkeys.rst +++ b/sites/docs/api/hostkeys.rst @@ -2,6 +2,3 @@ paramiko.hostkeys module ======================== .. automodule:: paramiko.hostkeys - :members: - :undoc-members: - :show-inheritance: diff --git a/sites/docs/api/kex_gex.rst b/sites/docs/api/kex_gex.rst index 749853b3..9b5ff543 100644 --- a/sites/docs/api/kex_gex.rst +++ b/sites/docs/api/kex_gex.rst @@ -2,6 +2,3 @@ paramiko.kex_gex module ======================= .. automodule:: paramiko.kex_gex - :members: - :undoc-members: - :show-inheritance: diff --git a/sites/docs/api/kex_group1.rst b/sites/docs/api/kex_group1.rst index 8bef58d0..47089326 100644 --- a/sites/docs/api/kex_group1.rst +++ b/sites/docs/api/kex_group1.rst @@ -2,6 +2,3 @@ paramiko.kex_group1 module ========================== .. automodule:: paramiko.kex_group1 - :members: - :undoc-members: - :show-inheritance: diff --git a/sites/docs/api/logging22.rst b/sites/docs/api/logging22.rst index 55c17882..fad43489 100644 --- a/sites/docs/api/logging22.rst +++ b/sites/docs/api/logging22.rst @@ -2,6 +2,3 @@ paramiko.logging22 module ========================= .. automodule:: paramiko.logging22 - :members: - :undoc-members: - :show-inheritance: diff --git a/sites/docs/api/message.rst b/sites/docs/api/message.rst index 4f7b5838..e660ef89 100644 --- a/sites/docs/api/message.rst +++ b/sites/docs/api/message.rst @@ -2,6 +2,3 @@ paramiko.message module ======================= .. automodule:: paramiko.message - :members: - :undoc-members: - :show-inheritance: diff --git a/sites/docs/api/packet.rst b/sites/docs/api/packet.rst index 6a127d7a..ab7c6b45 100644 --- a/sites/docs/api/packet.rst +++ b/sites/docs/api/packet.rst @@ -2,6 +2,3 @@ paramiko.packet module ====================== .. automodule:: paramiko.packet - :members: - :undoc-members: - :show-inheritance: diff --git a/sites/docs/api/pipe.rst b/sites/docs/api/pipe.rst index 5ec75fa5..220dbc87 100644 --- a/sites/docs/api/pipe.rst +++ b/sites/docs/api/pipe.rst @@ -2,6 +2,3 @@ paramiko.pipe module ==================== .. automodule:: paramiko.pipe - :members: - :undoc-members: - :show-inheritance: diff --git a/sites/docs/api/pkey.rst b/sites/docs/api/pkey.rst index fb75e664..418736b7 100644 --- a/sites/docs/api/pkey.rst +++ b/sites/docs/api/pkey.rst @@ -2,6 +2,3 @@ paramiko.pkey module ==================== .. automodule:: paramiko.pkey - :members: - :undoc-members: - :show-inheritance: diff --git a/sites/docs/api/primes.rst b/sites/docs/api/primes.rst index 8dfe2a47..4d7a1f58 100644 --- a/sites/docs/api/primes.rst +++ b/sites/docs/api/primes.rst @@ -2,6 +2,3 @@ paramiko.primes module ====================== .. automodule:: paramiko.primes - :members: - :undoc-members: - :show-inheritance: diff --git a/sites/docs/api/proxy.rst b/sites/docs/api/proxy.rst index 5a0f5aff..e3cf59ca 100644 --- a/sites/docs/api/proxy.rst +++ b/sites/docs/api/proxy.rst @@ -2,6 +2,3 @@ paramiko.proxy module ===================== .. automodule:: paramiko.proxy - :members: - :undoc-members: - :show-inheritance: diff --git a/sites/docs/api/resource.rst b/sites/docs/api/resource.rst index a4527ab1..c4c548f4 100644 --- a/sites/docs/api/resource.rst +++ b/sites/docs/api/resource.rst @@ -2,6 +2,3 @@ paramiko.resource module ======================== .. automodule:: paramiko.resource - :members: - :undoc-members: - :show-inheritance: diff --git a/sites/docs/api/rsakey.rst b/sites/docs/api/rsakey.rst index 7ad995ce..77dbd894 100644 --- a/sites/docs/api/rsakey.rst +++ b/sites/docs/api/rsakey.rst @@ -2,6 +2,3 @@ paramiko.rsakey module ====================== .. automodule:: paramiko.rsakey - :members: - :undoc-members: - :show-inheritance: diff --git a/sites/docs/api/server.rst b/sites/docs/api/server.rst index 3821c9be..f59b1216 100644 --- a/sites/docs/api/server.rst +++ b/sites/docs/api/server.rst @@ -2,6 +2,3 @@ paramiko.server module ====================== .. automodule:: paramiko.server - :members: - :undoc-members: - :show-inheritance: diff --git a/sites/docs/api/sftp.rst b/sites/docs/api/sftp.rst index 1d65900a..731c2521 100644 --- a/sites/docs/api/sftp.rst +++ b/sites/docs/api/sftp.rst @@ -2,6 +2,3 @@ paramiko.sftp module ==================== .. automodule:: paramiko.sftp - :members: - :undoc-members: - :show-inheritance: diff --git a/sites/docs/api/sftp_attr.rst b/sites/docs/api/sftp_attr.rst index 114748c6..98bce03a 100644 --- a/sites/docs/api/sftp_attr.rst +++ b/sites/docs/api/sftp_attr.rst @@ -2,6 +2,3 @@ paramiko.sftp_attr module ========================= .. automodule:: paramiko.sftp_attr - :members: - :undoc-members: - :show-inheritance: diff --git a/sites/docs/api/sftp_client.rst b/sites/docs/api/sftp_client.rst index ee973df2..9892befe 100644 --- a/sites/docs/api/sftp_client.rst +++ b/sites/docs/api/sftp_client.rst @@ -2,6 +2,3 @@ paramiko.sftp_client module =========================== .. automodule:: paramiko.sftp_client - :members: - :undoc-members: - :show-inheritance: diff --git a/sites/docs/api/sftp_file.rst b/sites/docs/api/sftp_file.rst index 77756807..7df6e12b 100644 --- a/sites/docs/api/sftp_file.rst +++ b/sites/docs/api/sftp_file.rst @@ -2,6 +2,3 @@ paramiko.sftp_file module ========================= .. automodule:: paramiko.sftp_file - :members: - :undoc-members: - :show-inheritance: diff --git a/sites/docs/api/sftp_handle.rst b/sites/docs/api/sftp_handle.rst index 0f563b16..1d1c30ed 100644 --- a/sites/docs/api/sftp_handle.rst +++ b/sites/docs/api/sftp_handle.rst @@ -2,6 +2,3 @@ paramiko.sftp_handle module =========================== .. automodule:: paramiko.sftp_handle - :members: - :undoc-members: - :show-inheritance: diff --git a/sites/docs/api/sftp_server.rst b/sites/docs/api/sftp_server.rst index 50e84b18..82a6976e 100644 --- a/sites/docs/api/sftp_server.rst +++ b/sites/docs/api/sftp_server.rst @@ -2,6 +2,3 @@ paramiko.sftp_server module =========================== .. automodule:: paramiko.sftp_server - :members: - :undoc-members: - :show-inheritance: diff --git a/sites/docs/api/sftp_si.rst b/sites/docs/api/sftp_si.rst index e369d879..d071e61a 100644 --- a/sites/docs/api/sftp_si.rst +++ b/sites/docs/api/sftp_si.rst @@ -2,6 +2,3 @@ paramiko.sftp_si module ======================= .. automodule:: paramiko.sftp_si - :members: - :undoc-members: - :show-inheritance: diff --git a/sites/docs/api/ssh_exception.rst b/sites/docs/api/ssh_exception.rst index a4b6d2aa..7faaf5f4 100644 --- a/sites/docs/api/ssh_exception.rst +++ b/sites/docs/api/ssh_exception.rst @@ -2,6 +2,3 @@ paramiko.ssh_exception module ============================= .. automodule:: paramiko.ssh_exception - :members: - :undoc-members: - :show-inheritance: diff --git a/sites/docs/api/transport.rst b/sites/docs/api/transport.rst index 19fb0e88..6f5b1cd9 100644 --- a/sites/docs/api/transport.rst +++ b/sites/docs/api/transport.rst @@ -2,6 +2,3 @@ paramiko.transport module ========================= .. automodule:: paramiko.transport - :members: - :undoc-members: - :show-inheritance: diff --git a/sites/docs/api/util.rst b/sites/docs/api/util.rst index ae3eae0f..de383ae1 100644 --- a/sites/docs/api/util.rst +++ b/sites/docs/api/util.rst @@ -2,6 +2,3 @@ paramiko.util module ==================== .. automodule:: paramiko.util - :members: - :undoc-members: - :show-inheritance: diff --git a/sites/docs/api/win_pageant.rst b/sites/docs/api/win_pageant.rst index 561a5143..9b488080 100644 --- a/sites/docs/api/win_pageant.rst +++ b/sites/docs/api/win_pageant.rst @@ -2,6 +2,3 @@ paramiko.win_pageant module =========================== .. automodule:: paramiko.win_pageant - :members: - :undoc-members: - :show-inheritance: -- cgit v1.2.3 From e0ff365388702492b83816a42cc6e692cd15c542 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Fri, 14 Feb 2014 16:50:16 -0800 Subject: Agent title --- sites/docs/api/agent.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'sites') diff --git a/sites/docs/api/agent.rst b/sites/docs/api/agent.rst index 26d9c97a..74edc184 100644 --- a/sites/docs/api/agent.rst +++ b/sites/docs/api/agent.rst @@ -1,4 +1,4 @@ -paramiko.agent module -===================== +Agent +===== .. automodule:: paramiko.agent -- cgit v1.2.3 From 70218ff852370e78e85425c22c100895f805c5a3 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Fri, 14 Feb 2014 16:50:32 -0800 Subject: Auth handler is purely internal and has no docstrings --- sites/docs/api/auth_handler.rst | 4 ---- 1 file changed, 4 deletions(-) delete mode 100644 sites/docs/api/auth_handler.rst (limited to 'sites') diff --git a/sites/docs/api/auth_handler.rst b/sites/docs/api/auth_handler.rst deleted file mode 100644 index 0fdb490f..00000000 --- a/sites/docs/api/auth_handler.rst +++ /dev/null @@ -1,4 +0,0 @@ -paramiko.auth_handler module -============================ - -.. automodule:: paramiko.auth_handler -- cgit v1.2.3 From f855937d10857a39c63783b610a2838e2fa8400d Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Fri, 14 Feb 2014 16:50:56 -0800 Subject: Ditto for BER --- sites/docs/api/ber.rst | 4 ---- 1 file changed, 4 deletions(-) delete mode 100644 sites/docs/api/ber.rst (limited to 'sites') diff --git a/sites/docs/api/ber.rst b/sites/docs/api/ber.rst deleted file mode 100644 index 20ab604e..00000000 --- a/sites/docs/api/ber.rst +++ /dev/null @@ -1,4 +0,0 @@ -paramiko.ber module -=================== - -.. automodule:: paramiko.ber -- cgit v1.2.3 From 34243a4aa28192c30e80a7d61271623d397deb86 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Fri, 14 Feb 2014 16:51:59 -0800 Subject: Buffered pipe --- sites/docs/api/buffered_pipe.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'sites') diff --git a/sites/docs/api/buffered_pipe.rst b/sites/docs/api/buffered_pipe.rst index a8cdb581..54d87c59 100644 --- a/sites/docs/api/buffered_pipe.rst +++ b/sites/docs/api/buffered_pipe.rst @@ -1,4 +1,4 @@ -paramiko.buffered_pipe module -============================= +Buffered pipes +============== .. automodule:: paramiko.buffered_pipe -- cgit v1.2.3 From 6ff6e149789cbb8fb9a7791e601737044b931716 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Fri, 14 Feb 2014 16:54:50 -0800 Subject: Moar headers. Going with plural where appropriate. --- sites/docs/api/agent.rst | 4 ++-- sites/docs/api/channel.rst | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) (limited to 'sites') diff --git a/sites/docs/api/agent.rst b/sites/docs/api/agent.rst index 74edc184..789f7b1d 100644 --- a/sites/docs/api/agent.rst +++ b/sites/docs/api/agent.rst @@ -1,4 +1,4 @@ -Agent -===== +SSH Agents +========== .. automodule:: paramiko.agent diff --git a/sites/docs/api/channel.rst b/sites/docs/api/channel.rst index db8280b5..3edb8ac7 100644 --- a/sites/docs/api/channel.rst +++ b/sites/docs/api/channel.rst @@ -1,4 +1,4 @@ -paramiko.channel module -======================= +Channels +======== .. automodule:: paramiko.channel -- cgit v1.2.3 From ef9c0a655ad08d74747281499081d0b8c92c936f Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Fri, 14 Feb 2014 17:02:13 -0800 Subject: Common module has no interesting docs in it Also no clear way to auto-display all data members versus using a bunch of awful explicit autodata:: directives. Can dig later if anybody cares. --- sites/docs/api/common.rst | 4 ---- 1 file changed, 4 deletions(-) delete mode 100644 sites/docs/api/common.rst (limited to 'sites') diff --git a/sites/docs/api/common.rst b/sites/docs/api/common.rst deleted file mode 100644 index fb99f218..00000000 --- a/sites/docs/api/common.rst +++ /dev/null @@ -1,4 +0,0 @@ -paramiko.common module -====================== - -.. automodule:: paramiko.common -- cgit v1.2.3 From a67142b1cae4fb04fc99df706b8b9b92337ee88f Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Fri, 14 Feb 2014 17:03:02 -0800 Subject: Moar header --- sites/docs/api/client.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'sites') diff --git a/sites/docs/api/client.rst b/sites/docs/api/client.rst index 840ffec8..a0784d09 100644 --- a/sites/docs/api/client.rst +++ b/sites/docs/api/client.rst @@ -1,4 +1,4 @@ -paramiko.client module -====================== +Clients +======= .. automodule:: paramiko.client -- cgit v1.2.3 From 6d412b06a16a12169f0f71927fbef11638242700 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Fri, 14 Feb 2014 17:03:12 -0800 Subject: Another undocumented/internal module --- sites/docs/api/compress.rst | 4 ---- 1 file changed, 4 deletions(-) delete mode 100644 sites/docs/api/compress.rst (limited to 'sites') diff --git a/sites/docs/api/compress.rst b/sites/docs/api/compress.rst deleted file mode 100644 index 93e04231..00000000 --- a/sites/docs/api/compress.rst +++ /dev/null @@ -1,4 +0,0 @@ -paramiko.compress module -======================== - -.. automodule:: paramiko.compress -- cgit v1.2.3 From 48adf5c646c8a2fe86a6670f54a434533814ab89 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Fri, 14 Feb 2014 17:05:05 -0800 Subject: Consolidate rsa/dss keys into one doc module --- sites/docs/api/dsskey.rst | 4 ---- sites/docs/api/keys.rst | 5 +++++ sites/docs/api/rsakey.rst | 4 ---- 3 files changed, 5 insertions(+), 8 deletions(-) delete mode 100644 sites/docs/api/dsskey.rst create mode 100644 sites/docs/api/keys.rst delete mode 100644 sites/docs/api/rsakey.rst (limited to 'sites') diff --git a/sites/docs/api/dsskey.rst b/sites/docs/api/dsskey.rst deleted file mode 100644 index c4d8d652..00000000 --- a/sites/docs/api/dsskey.rst +++ /dev/null @@ -1,4 +0,0 @@ -paramiko.dsskey module -====================== - -.. automodule:: paramiko.dsskey diff --git a/sites/docs/api/keys.rst b/sites/docs/api/keys.rst new file mode 100644 index 00000000..ca09a878 --- /dev/null +++ b/sites/docs/api/keys.rst @@ -0,0 +1,5 @@ +Key handling +============ + +.. automodule:: paramiko.dsskey +.. automodule:: paramiko.rsakey diff --git a/sites/docs/api/rsakey.rst b/sites/docs/api/rsakey.rst deleted file mode 100644 index 77dbd894..00000000 --- a/sites/docs/api/rsakey.rst +++ /dev/null @@ -1,4 +0,0 @@ -paramiko.rsakey module -====================== - -.. automodule:: paramiko.rsakey -- cgit v1.2.3 From 370af8979145ef09dbf606677d1d4d7f61b67281 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Fri, 14 Feb 2014 17:05:09 -0800 Subject: Header --- sites/docs/api/config.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'sites') diff --git a/sites/docs/api/config.rst b/sites/docs/api/config.rst index dc030b48..0a9fa1dc 100644 --- a/sites/docs/api/config.rst +++ b/sites/docs/api/config.rst @@ -1,4 +1,4 @@ -paramiko.config module +Configuration handling ====================== .. automodule:: paramiko.config -- cgit v1.2.3 From 960b3c038da0b41d956a1e31a18827533b153ed8 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Fri, 14 Feb 2014 17:08:30 -0800 Subject: More undocumented/internal modules --- sites/docs/api/kex_gex.rst | 4 ---- sites/docs/api/kex_group1.rst | 4 ---- 2 files changed, 8 deletions(-) delete mode 100644 sites/docs/api/kex_gex.rst delete mode 100644 sites/docs/api/kex_group1.rst (limited to 'sites') diff --git a/sites/docs/api/kex_gex.rst b/sites/docs/api/kex_gex.rst deleted file mode 100644 index 9b5ff543..00000000 --- a/sites/docs/api/kex_gex.rst +++ /dev/null @@ -1,4 +0,0 @@ -paramiko.kex_gex module -======================= - -.. automodule:: paramiko.kex_gex diff --git a/sites/docs/api/kex_group1.rst b/sites/docs/api/kex_group1.rst deleted file mode 100644 index 47089326..00000000 --- a/sites/docs/api/kex_group1.rst +++ /dev/null @@ -1,4 +0,0 @@ -paramiko.kex_group1 module -========================== - -.. automodule:: paramiko.kex_group1 -- cgit v1.2.3 From da6d00dcb7f20ed0c37dcb94add875bd3c1c40d7 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Fri, 14 Feb 2014 17:08:36 -0800 Subject: More headers --- sites/docs/api/file.rst | 4 ++-- sites/docs/api/hostkeys.rst | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) (limited to 'sites') diff --git a/sites/docs/api/file.rst b/sites/docs/api/file.rst index d16c834f..199f3ecc 100644 --- a/sites/docs/api/file.rst +++ b/sites/docs/api/file.rst @@ -1,4 +1,4 @@ -paramiko.file module -==================== +Buffered files +============== .. automodule:: paramiko.file diff --git a/sites/docs/api/hostkeys.rst b/sites/docs/api/hostkeys.rst index 5379a369..b57a2c6c 100644 --- a/sites/docs/api/hostkeys.rst +++ b/sites/docs/api/hostkeys.rst @@ -1,4 +1,4 @@ -paramiko.hostkeys module -======================== +Host key / known_hosts handling +=============================== .. automodule:: paramiko.hostkeys -- cgit v1.2.3 From b9d25a30b6e1f2691c5e716694d26fcfd4798502 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Fri, 14 Feb 2014 17:08:59 -0800 Subject: LOL no --- sites/docs/api/logging22.rst | 4 ---- 1 file changed, 4 deletions(-) delete mode 100644 sites/docs/api/logging22.rst (limited to 'sites') diff --git a/sites/docs/api/logging22.rst b/sites/docs/api/logging22.rst deleted file mode 100644 index fad43489..00000000 --- a/sites/docs/api/logging22.rst +++ /dev/null @@ -1,4 +0,0 @@ -paramiko.logging22 module -========================= - -.. automodule:: paramiko.logging22 -- cgit v1.2.3 From ac63ed58a14dacf508b00a1df787cb41ed8b65dc Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Fri, 14 Feb 2014 17:11:51 -0800 Subject: Missed one re: keys modules --- sites/docs/api/keys.rst | 1 + sites/docs/api/pkey.rst | 4 ---- 2 files changed, 1 insertion(+), 4 deletions(-) delete mode 100644 sites/docs/api/pkey.rst (limited to 'sites') diff --git a/sites/docs/api/keys.rst b/sites/docs/api/keys.rst index ca09a878..af7b58c4 100644 --- a/sites/docs/api/keys.rst +++ b/sites/docs/api/keys.rst @@ -1,5 +1,6 @@ Key handling ============ +.. automodule:: paramiko.pkey .. automodule:: paramiko.dsskey .. automodule:: paramiko.rsakey diff --git a/sites/docs/api/pkey.rst b/sites/docs/api/pkey.rst deleted file mode 100644 index 418736b7..00000000 --- a/sites/docs/api/pkey.rst +++ /dev/null @@ -1,4 +0,0 @@ -paramiko.pkey module -==================== - -.. automodule:: paramiko.pkey -- cgit v1.2.3 From 29433436657381058a7da13aa8dcad2e27634a52 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Fri, 14 Feb 2014 17:12:00 -0800 Subject: Yup. Headers. --- sites/docs/api/message.rst | 4 ++-- sites/docs/api/packet.rst | 4 ++-- sites/docs/api/pipe.rst | 4 ++-- 3 files changed, 6 insertions(+), 6 deletions(-) (limited to 'sites') diff --git a/sites/docs/api/message.rst b/sites/docs/api/message.rst index e660ef89..986548b5 100644 --- a/sites/docs/api/message.rst +++ b/sites/docs/api/message.rst @@ -1,4 +1,4 @@ -paramiko.message module -======================= +Protocol messages +================= .. automodule:: paramiko.message diff --git a/sites/docs/api/packet.rst b/sites/docs/api/packet.rst index ab7c6b45..72ad5591 100644 --- a/sites/docs/api/packet.rst +++ b/sites/docs/api/packet.rst @@ -1,4 +1,4 @@ -paramiko.packet module -====================== +Packet handling +=============== .. automodule:: paramiko.packet diff --git a/sites/docs/api/pipe.rst b/sites/docs/api/pipe.rst index 220dbc87..e480446f 100644 --- a/sites/docs/api/pipe.rst +++ b/sites/docs/api/pipe.rst @@ -1,4 +1,4 @@ -paramiko.pipe module -==================== +Cross-platform pipe implementations +=================================== .. automodule:: paramiko.pipe -- cgit v1.2.3 From c8d97d78c44929be0bfd569425ff6027f225378b Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Fri, 14 Feb 2014 17:12:27 -0800 Subject: More internals --- sites/docs/api/primes.rst | 4 ---- sites/docs/api/resource.rst | 4 ---- 2 files changed, 8 deletions(-) delete mode 100644 sites/docs/api/primes.rst delete mode 100644 sites/docs/api/resource.rst (limited to 'sites') diff --git a/sites/docs/api/primes.rst b/sites/docs/api/primes.rst deleted file mode 100644 index 4d7a1f58..00000000 --- a/sites/docs/api/primes.rst +++ /dev/null @@ -1,4 +0,0 @@ -paramiko.primes module -====================== - -.. automodule:: paramiko.primes diff --git a/sites/docs/api/resource.rst b/sites/docs/api/resource.rst deleted file mode 100644 index c4c548f4..00000000 --- a/sites/docs/api/resource.rst +++ /dev/null @@ -1,4 +0,0 @@ -paramiko.resource module -======================== - -.. automodule:: paramiko.resource -- cgit v1.2.3 From 09c0006a40598e224a3a925e894573d0d0cbb4c1 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Fri, 14 Feb 2014 17:17:10 -0800 Subject: Consolidate SFTP docs --- sites/docs/api/sftp.rst | 10 ++++++++-- sites/docs/api/sftp_attr.rst | 4 ---- sites/docs/api/sftp_client.rst | 4 ---- sites/docs/api/sftp_file.rst | 4 ---- sites/docs/api/sftp_handle.rst | 4 ---- sites/docs/api/sftp_server.rst | 4 ---- sites/docs/api/sftp_si.rst | 4 ---- 7 files changed, 8 insertions(+), 26 deletions(-) delete mode 100644 sites/docs/api/sftp_attr.rst delete mode 100644 sites/docs/api/sftp_client.rst delete mode 100644 sites/docs/api/sftp_file.rst delete mode 100644 sites/docs/api/sftp_handle.rst delete mode 100644 sites/docs/api/sftp_server.rst delete mode 100644 sites/docs/api/sftp_si.rst (limited to 'sites') diff --git a/sites/docs/api/sftp.rst b/sites/docs/api/sftp.rst index 731c2521..2eedecf8 100644 --- a/sites/docs/api/sftp.rst +++ b/sites/docs/api/sftp.rst @@ -1,4 +1,10 @@ -paramiko.sftp module -==================== +SFTP +==== .. automodule:: paramiko.sftp +.. automodule:: paramiko.sftp_attr +.. automodule:: paramiko.sftp_client +.. automodule:: paramiko.sftp_file +.. automodule:: paramiko.sftp_handle +.. automodule:: paramiko.sftp_server +.. automodule:: paramiko.sftp_si diff --git a/sites/docs/api/sftp_attr.rst b/sites/docs/api/sftp_attr.rst deleted file mode 100644 index 98bce03a..00000000 --- a/sites/docs/api/sftp_attr.rst +++ /dev/null @@ -1,4 +0,0 @@ -paramiko.sftp_attr module -========================= - -.. automodule:: paramiko.sftp_attr diff --git a/sites/docs/api/sftp_client.rst b/sites/docs/api/sftp_client.rst deleted file mode 100644 index 9892befe..00000000 --- a/sites/docs/api/sftp_client.rst +++ /dev/null @@ -1,4 +0,0 @@ -paramiko.sftp_client module -=========================== - -.. automodule:: paramiko.sftp_client diff --git a/sites/docs/api/sftp_file.rst b/sites/docs/api/sftp_file.rst deleted file mode 100644 index 7df6e12b..00000000 --- a/sites/docs/api/sftp_file.rst +++ /dev/null @@ -1,4 +0,0 @@ -paramiko.sftp_file module -========================= - -.. automodule:: paramiko.sftp_file diff --git a/sites/docs/api/sftp_handle.rst b/sites/docs/api/sftp_handle.rst deleted file mode 100644 index 1d1c30ed..00000000 --- a/sites/docs/api/sftp_handle.rst +++ /dev/null @@ -1,4 +0,0 @@ -paramiko.sftp_handle module -=========================== - -.. automodule:: paramiko.sftp_handle diff --git a/sites/docs/api/sftp_server.rst b/sites/docs/api/sftp_server.rst deleted file mode 100644 index 82a6976e..00000000 --- a/sites/docs/api/sftp_server.rst +++ /dev/null @@ -1,4 +0,0 @@ -paramiko.sftp_server module -=========================== - -.. automodule:: paramiko.sftp_server diff --git a/sites/docs/api/sftp_si.rst b/sites/docs/api/sftp_si.rst deleted file mode 100644 index d071e61a..00000000 --- a/sites/docs/api/sftp_si.rst +++ /dev/null @@ -1,4 +0,0 @@ -paramiko.sftp_si module -======================= - -.. automodule:: paramiko.sftp_si -- cgit v1.2.3 From a627ecfb1450150e79fd4443c44acdffec807efd Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Fri, 14 Feb 2014 17:17:15 -0800 Subject: Even more headers --- sites/docs/api/proxy.rst | 4 ++-- sites/docs/api/server.rst | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) (limited to 'sites') diff --git a/sites/docs/api/proxy.rst b/sites/docs/api/proxy.rst index e3cf59ca..8f3e3a8b 100644 --- a/sites/docs/api/proxy.rst +++ b/sites/docs/api/proxy.rst @@ -1,4 +1,4 @@ -paramiko.proxy module -===================== +ProxyCommand support +==================== .. automodule:: paramiko.proxy diff --git a/sites/docs/api/server.rst b/sites/docs/api/server.rst index f59b1216..7519ae99 100644 --- a/sites/docs/api/server.rst +++ b/sites/docs/api/server.rst @@ -1,4 +1,4 @@ -paramiko.server module -====================== +Server implementation +===================== .. automodule:: paramiko.server -- cgit v1.2.3 From 6e4829c20fbd7cb25b5689571ad2f296aa9dd3fe Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Fri, 14 Feb 2014 17:18:06 -0800 Subject: More internals --- sites/docs/api/util.rst | 4 ---- 1 file changed, 4 deletions(-) delete mode 100644 sites/docs/api/util.rst (limited to 'sites') diff --git a/sites/docs/api/util.rst b/sites/docs/api/util.rst deleted file mode 100644 index de383ae1..00000000 --- a/sites/docs/api/util.rst +++ /dev/null @@ -1,4 +0,0 @@ -paramiko.util module -==================== - -.. automodule:: paramiko.util -- cgit v1.2.3 From 22766e96a65106cf8a3107bf432c0b8eb40cb681 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Fri, 14 Feb 2014 17:18:36 -0800 Subject: Last of headers! --- sites/docs/api/ssh_exception.rst | 4 ++-- sites/docs/api/transport.rst | 2 +- sites/docs/api/win_pageant.rst | 4 ++-- 3 files changed, 5 insertions(+), 5 deletions(-) (limited to 'sites') diff --git a/sites/docs/api/ssh_exception.rst b/sites/docs/api/ssh_exception.rst index 7faaf5f4..64872dc2 100644 --- a/sites/docs/api/ssh_exception.rst +++ b/sites/docs/api/ssh_exception.rst @@ -1,4 +1,4 @@ -paramiko.ssh_exception module -============================= +Exceptions +========== .. automodule:: paramiko.ssh_exception diff --git a/sites/docs/api/transport.rst b/sites/docs/api/transport.rst index 6f5b1cd9..f68b77dc 100644 --- a/sites/docs/api/transport.rst +++ b/sites/docs/api/transport.rst @@ -1,4 +1,4 @@ -paramiko.transport module +Transport (core protocol) ========================= .. automodule:: paramiko.transport diff --git a/sites/docs/api/win_pageant.rst b/sites/docs/api/win_pageant.rst index 9b488080..c48da5c6 100644 --- a/sites/docs/api/win_pageant.rst +++ b/sites/docs/api/win_pageant.rst @@ -1,4 +1,4 @@ -paramiko.win_pageant module -=========================== +WinPageant support +================== .. automodule:: paramiko.win_pageant -- cgit v1.2.3 From 0af6df924add72313594c12418d0a2cb45291e4a Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Fri, 14 Feb 2014 18:20:47 -0800 Subject: First stab at segmented TOCtrees. Makes sidebar TOC a little funny tho. --- sites/docs/api/transport.rst | 4 ++-- sites/docs/index.rst | 43 +++++++++++++++++++++++++++++++++++++++++-- 2 files changed, 43 insertions(+), 4 deletions(-) (limited to 'sites') diff --git a/sites/docs/api/transport.rst b/sites/docs/api/transport.rst index f68b77dc..1b54f04e 100644 --- a/sites/docs/api/transport.rst +++ b/sites/docs/api/transport.rst @@ -1,4 +1,4 @@ -Transport (core protocol) -========================= +Transport +========= .. automodule:: paramiko.transport diff --git a/sites/docs/index.rst b/sites/docs/index.rst index 89c75831..bca0e650 100644 --- a/sites/docs/index.rst +++ b/sites/docs/index.rst @@ -5,7 +5,46 @@ This site covers Paramiko's usage & API documentation. For basic info on what Paramiko is, including its public changelog & how the project is maintained, please see `the main website `_. + +API documentation +================= + +Core SSH protocol classes +------------------------- + +.. toctree:: + api/channel + api/client + api/message + api/packet + api/transport + + +Authentication & key handling +----------------------------- + .. toctree:: - :glob: + api/agent + api/hostkeys + api/keys + api/win_pageant - api/* + +Other primary functions +----------------------- + +.. toctree:: + api/config + api/proxy + api/server + api/sftp + + +Miscellany +---------- + +.. toctree:: + api/buffered_pipe + api/file + api/pipe + api/ssh_exception -- cgit v1.2.3 From a58cf80139ff0c8059eebe8bd0c55963a5a33f53 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Fri, 21 Feb 2014 09:56:14 -0800 Subject: Un-derp header levels --- sites/docs/index.rst | 1 + 1 file changed, 1 insertion(+) (limited to 'sites') diff --git a/sites/docs/index.rst b/sites/docs/index.rst index bca0e650..5133c244 100644 --- a/sites/docs/index.rst +++ b/sites/docs/index.rst @@ -1,3 +1,4 @@ +==================================== Welcome to Paramiko's documentation! ==================================== -- cgit v1.2.3 From 88140996a7a259e9e028b022c037223ee97c4c87 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Fri, 21 Feb 2014 09:58:19 -0800 Subject: Too much 'handling' --- sites/docs/api/config.rst | 4 ++-- sites/docs/api/hostkeys.rst | 4 ++-- sites/docs/index.rst | 4 ++-- 3 files changed, 6 insertions(+), 6 deletions(-) (limited to 'sites') diff --git a/sites/docs/api/config.rst b/sites/docs/api/config.rst index 0a9fa1dc..6f9d3ce3 100644 --- a/sites/docs/api/config.rst +++ b/sites/docs/api/config.rst @@ -1,4 +1,4 @@ -Configuration handling -====================== +Configuration +============= .. automodule:: paramiko.config diff --git a/sites/docs/api/hostkeys.rst b/sites/docs/api/hostkeys.rst index b57a2c6c..0859fbed 100644 --- a/sites/docs/api/hostkeys.rst +++ b/sites/docs/api/hostkeys.rst @@ -1,4 +1,4 @@ -Host key / known_hosts handling -=============================== +Host keys / ``known_hosts`` files +================================= .. automodule:: paramiko.hostkeys diff --git a/sites/docs/index.rst b/sites/docs/index.rst index 5133c244..98f4069a 100644 --- a/sites/docs/index.rst +++ b/sites/docs/index.rst @@ -21,8 +21,8 @@ Core SSH protocol classes api/transport -Authentication & key handling ------------------------------ +Authentication & keys +--------------------- .. toctree:: api/agent -- cgit v1.2.3 From 635108aab2e1f71024f68bfc47659cfea89496ea Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Fri, 21 Feb 2014 10:05:40 -0800 Subject: Formatting --- sites/docs/api/proxy.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'sites') diff --git a/sites/docs/api/proxy.rst b/sites/docs/api/proxy.rst index 8f3e3a8b..489b14e7 100644 --- a/sites/docs/api/proxy.rst +++ b/sites/docs/api/proxy.rst @@ -1,4 +1,4 @@ -ProxyCommand support -==================== +``ProxyCommand`` support +======================== .. automodule:: paramiko.proxy -- cgit v1.2.3 From d4148ab6f30fbea9d42e6999fb793a557a4d0f92 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Fri, 21 Feb 2014 10:20:57 -0800 Subject: Tweak core-class doc titles --- sites/docs/api/channel.rst | 4 ++-- sites/docs/api/client.rst | 4 ++-- sites/docs/api/message.rst | 4 ++-- sites/docs/api/packet.rst | 4 ++-- 4 files changed, 8 insertions(+), 8 deletions(-) (limited to 'sites') diff --git a/sites/docs/api/channel.rst b/sites/docs/api/channel.rst index 3edb8ac7..e71526f6 100644 --- a/sites/docs/api/channel.rst +++ b/sites/docs/api/channel.rst @@ -1,4 +1,4 @@ -Channels -======== +Channel +======= .. automodule:: paramiko.channel diff --git a/sites/docs/api/client.rst b/sites/docs/api/client.rst index a0784d09..1661f97d 100644 --- a/sites/docs/api/client.rst +++ b/sites/docs/api/client.rst @@ -1,4 +1,4 @@ -Clients -======= +Client +====== .. automodule:: paramiko.client diff --git a/sites/docs/api/message.rst b/sites/docs/api/message.rst index 986548b5..8d531e01 100644 --- a/sites/docs/api/message.rst +++ b/sites/docs/api/message.rst @@ -1,4 +1,4 @@ -Protocol messages -================= +Message +======= .. automodule:: paramiko.message diff --git a/sites/docs/api/packet.rst b/sites/docs/api/packet.rst index 72ad5591..4089203b 100644 --- a/sites/docs/api/packet.rst +++ b/sites/docs/api/packet.rst @@ -1,4 +1,4 @@ -Packet handling -=============== +Packetizer +========== .. automodule:: paramiko.packet -- cgit v1.2.3 From eb332c781bf26a96a472f970550938ccba118056 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Fri, 21 Feb 2014 10:21:19 -0800 Subject: Reorganize Client so API doc flows better --- paramiko/client.py | 115 +++++++++++++++++++++++----------------------- sites/docs/api/client.rst | 1 + 2 files changed, 58 insertions(+), 58 deletions(-) (limited to 'sites') diff --git a/paramiko/client.py b/paramiko/client.py index 19a09c2d..c7f9cfc8 100644 --- a/paramiko/client.py +++ b/paramiko/client.py @@ -17,7 +17,7 @@ # 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA. """ -:class:`SSHClient`. +SSH client & key policies """ from binascii import hexlify @@ -38,63 +38,6 @@ from paramiko.transport import Transport from paramiko.util import retry_on_signal -class MissingHostKeyPolicy (object): - """ - Interface for defining the policy that :class:`SSHClient` should use when the - SSH server's hostname is not in either the system host keys or the - application's keys. Pre-made classes implement policies for automatically - adding the key to the application's :class:`HostKeys` object (:class:`AutoAddPolicy`), - and for automatically rejecting the key (:class:`RejectPolicy`). - - This function may be used to ask the user to verify the key, for example. - """ - - def missing_host_key(self, client, hostname, key): - """ - Called when an :class:`SSHClient` receives a server key for a server that - isn't in either the system or local :class:`HostKeys` object. To accept - the key, simply return. To reject, raised an exception (which will - be passed to the calling application). - """ - pass - - -class AutoAddPolicy (MissingHostKeyPolicy): - """ - Policy for automatically adding the hostname and new host key to the - local :class:`HostKeys` object, and saving it. This is used by :class:`SSHClient`. - """ - - def missing_host_key(self, client, hostname, key): - client._host_keys.add(hostname, key.get_name(), key) - if client._host_keys_filename is not None: - client.save_host_keys(client._host_keys_filename) - client._log(DEBUG, 'Adding %s host key for %s: %s' % - (key.get_name(), hostname, hexlify(key.get_fingerprint()))) - - -class RejectPolicy (MissingHostKeyPolicy): - """ - Policy for automatically rejecting the unknown hostname & key. This is - used by :class:`SSHClient`. - """ - - def missing_host_key(self, client, hostname, key): - client._log(DEBUG, 'Rejecting %s host key for %s: %s' % - (key.get_name(), hostname, hexlify(key.get_fingerprint()))) - raise SSHException('Server %r not found in known_hosts' % hostname) - - -class WarningPolicy (MissingHostKeyPolicy): - """ - Policy for logging a python-style warning for an unknown host key, but - accepting it. This is used by :class:`SSHClient`. - """ - def missing_host_key(self, client, hostname, key): - warnings.warn('Unknown %s host key for %s: %s' % - (key.get_name(), hostname, hexlify(key.get_fingerprint()))) - - class SSHClient (object): """ A high-level representation of a session with an SSH server. This class @@ -536,3 +479,59 @@ class SSHClient (object): def _log(self, level, msg): self._transport._log(level, msg) + +class MissingHostKeyPolicy (object): + """ + Interface for defining the policy that :class:`SSHClient` should use when the + SSH server's hostname is not in either the system host keys or the + application's keys. Pre-made classes implement policies for automatically + adding the key to the application's :class:`HostKeys` object (:class:`AutoAddPolicy`), + and for automatically rejecting the key (:class:`RejectPolicy`). + + This function may be used to ask the user to verify the key, for example. + """ + + def missing_host_key(self, client, hostname, key): + """ + Called when an :class:`SSHClient` receives a server key for a server that + isn't in either the system or local :class:`HostKeys` object. To accept + the key, simply return. To reject, raised an exception (which will + be passed to the calling application). + """ + pass + + +class AutoAddPolicy (MissingHostKeyPolicy): + """ + Policy for automatically adding the hostname and new host key to the + local :class:`HostKeys` object, and saving it. This is used by :class:`SSHClient`. + """ + + def missing_host_key(self, client, hostname, key): + client._host_keys.add(hostname, key.get_name(), key) + if client._host_keys_filename is not None: + client.save_host_keys(client._host_keys_filename) + client._log(DEBUG, 'Adding %s host key for %s: %s' % + (key.get_name(), hostname, hexlify(key.get_fingerprint()))) + + +class RejectPolicy (MissingHostKeyPolicy): + """ + Policy for automatically rejecting the unknown hostname & key. This is + used by :class:`SSHClient`. + """ + + def missing_host_key(self, client, hostname, key): + client._log(DEBUG, 'Rejecting %s host key for %s: %s' % + (key.get_name(), hostname, hexlify(key.get_fingerprint()))) + raise SSHException('Server %r not found in known_hosts' % hostname) + + +class WarningPolicy (MissingHostKeyPolicy): + """ + Policy for logging a python-style warning for an unknown host key, but + accepting it. This is used by :class:`SSHClient`. + """ + def missing_host_key(self, client, hostname, key): + warnings.warn('Unknown %s host key for %s: %s' % + (key.get_name(), hostname, hexlify(key.get_fingerprint()))) diff --git a/sites/docs/api/client.rst b/sites/docs/api/client.rst index 1661f97d..b201812f 100644 --- a/sites/docs/api/client.rst +++ b/sites/docs/api/client.rst @@ -2,3 +2,4 @@ Client ====== .. automodule:: paramiko.client + :member-order: bysource -- cgit v1.2.3 From f40bf59ff3d18e7a0d8cdf685df09efaeb3b126e Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Fri, 21 Feb 2014 10:25:56 -0800 Subject: Source ordering updates for Transport --- paramiko/transport.py | 246 +++++++++++++++++++++---------------------- sites/docs/api/transport.rst | 1 + 2 files changed, 124 insertions(+), 123 deletions(-) (limited to 'sites') diff --git a/paramiko/transport.py b/paramiko/transport.py index 7cccd5ff..8be0ca37 100644 --- a/paramiko/transport.py +++ b/paramiko/transport.py @@ -17,7 +17,7 @@ # 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA. """ -:class:`Transport` handles the core SSH2 protocol. +Core protocol implementation """ import os @@ -66,128 +66,6 @@ import atexit atexit.register(_join_lingering_threads) -class SecurityOptions (object): - """ - Simple object containing the security preferences of an ssh transport. - These are tuples of acceptable ciphers, digests, key types, and key - exchange algorithms, listed in order of preference. - - Changing the contents and/or order of these fields affects the underlying - :class:`Transport` (but only if you change them before starting the session). - If you try to add an algorithm that paramiko doesn't recognize, - ``ValueError`` will be raised. If you try to assign something besides a - tuple to one of the fields, ``TypeError`` will be raised. - """ - __slots__ = [ 'ciphers', 'digests', 'key_types', 'kex', 'compression', '_transport' ] - - def __init__(self, transport): - self._transport = transport - - def __repr__(self): - """ - Returns a string representation of this object, for debugging. - - :rtype: str - """ - return '' % repr(self._transport) - - def _get_ciphers(self): - return self._transport._preferred_ciphers - - def _get_digests(self): - return self._transport._preferred_macs - - def _get_key_types(self): - return self._transport._preferred_keys - - def _get_kex(self): - return self._transport._preferred_kex - - def _get_compression(self): - return self._transport._preferred_compression - - def _set(self, name, orig, x): - if type(x) is list: - x = tuple(x) - if type(x) is not tuple: - raise TypeError('expected tuple or list') - possible = getattr(self._transport, orig).keys() - forbidden = filter(lambda n: n not in possible, x) - if len(forbidden) > 0: - raise ValueError('unknown cipher') - setattr(self._transport, name, x) - - def _set_ciphers(self, x): - self._set('_preferred_ciphers', '_cipher_info', x) - - def _set_digests(self, x): - self._set('_preferred_macs', '_mac_info', x) - - def _set_key_types(self, x): - self._set('_preferred_keys', '_key_info', x) - - def _set_kex(self, x): - self._set('_preferred_kex', '_kex_info', x) - - def _set_compression(self, x): - self._set('_preferred_compression', '_compression_info', x) - - ciphers = property(_get_ciphers, _set_ciphers, None, - "Symmetric encryption ciphers") - digests = property(_get_digests, _set_digests, None, - "Digest (one-way hash) algorithms") - key_types = property(_get_key_types, _set_key_types, None, - "Public-key algorithms") - kex = property(_get_kex, _set_kex, None, "Key exchange algorithms") - compression = property(_get_compression, _set_compression, None, - "Compression algorithms") - - -class ChannelMap (object): - def __init__(self): - # (id -> Channel) - self._map = weakref.WeakValueDictionary() - self._lock = threading.Lock() - - def put(self, chanid, chan): - self._lock.acquire() - try: - self._map[chanid] = chan - finally: - self._lock.release() - - def get(self, chanid): - self._lock.acquire() - try: - return self._map.get(chanid, None) - finally: - self._lock.release() - - def delete(self, chanid): - self._lock.acquire() - try: - try: - del self._map[chanid] - except KeyError: - pass - finally: - self._lock.release() - - def values(self): - self._lock.acquire() - try: - return self._map.values() - finally: - self._lock.release() - - def __len__(self): - self._lock.acquire() - try: - return len(self._map) - finally: - self._lock.release() - - class Transport (threading.Thread): """ An SSH Transport attaches to a stream (usually a socket), negotiates an @@ -2154,3 +2032,125 @@ class Transport (threading.Thread): MSG_CHANNEL_EOF: Channel._handle_eof, MSG_CHANNEL_CLOSE: Channel._handle_close, } + + +class SecurityOptions (object): + """ + Simple object containing the security preferences of an ssh transport. + These are tuples of acceptable ciphers, digests, key types, and key + exchange algorithms, listed in order of preference. + + Changing the contents and/or order of these fields affects the underlying + :class:`Transport` (but only if you change them before starting the session). + If you try to add an algorithm that paramiko doesn't recognize, + ``ValueError`` will be raised. If you try to assign something besides a + tuple to one of the fields, ``TypeError`` will be raised. + """ + __slots__ = [ 'ciphers', 'digests', 'key_types', 'kex', 'compression', '_transport' ] + + def __init__(self, transport): + self._transport = transport + + def __repr__(self): + """ + Returns a string representation of this object, for debugging. + + :rtype: str + """ + return '' % repr(self._transport) + + def _get_ciphers(self): + return self._transport._preferred_ciphers + + def _get_digests(self): + return self._transport._preferred_macs + + def _get_key_types(self): + return self._transport._preferred_keys + + def _get_kex(self): + return self._transport._preferred_kex + + def _get_compression(self): + return self._transport._preferred_compression + + def _set(self, name, orig, x): + if type(x) is list: + x = tuple(x) + if type(x) is not tuple: + raise TypeError('expected tuple or list') + possible = getattr(self._transport, orig).keys() + forbidden = filter(lambda n: n not in possible, x) + if len(forbidden) > 0: + raise ValueError('unknown cipher') + setattr(self._transport, name, x) + + def _set_ciphers(self, x): + self._set('_preferred_ciphers', '_cipher_info', x) + + def _set_digests(self, x): + self._set('_preferred_macs', '_mac_info', x) + + def _set_key_types(self, x): + self._set('_preferred_keys', '_key_info', x) + + def _set_kex(self, x): + self._set('_preferred_kex', '_kex_info', x) + + def _set_compression(self, x): + self._set('_preferred_compression', '_compression_info', x) + + ciphers = property(_get_ciphers, _set_ciphers, None, + "Symmetric encryption ciphers") + digests = property(_get_digests, _set_digests, None, + "Digest (one-way hash) algorithms") + key_types = property(_get_key_types, _set_key_types, None, + "Public-key algorithms") + kex = property(_get_kex, _set_kex, None, "Key exchange algorithms") + compression = property(_get_compression, _set_compression, None, + "Compression algorithms") + + +class ChannelMap (object): + def __init__(self): + # (id -> Channel) + self._map = weakref.WeakValueDictionary() + self._lock = threading.Lock() + + def put(self, chanid, chan): + self._lock.acquire() + try: + self._map[chanid] = chan + finally: + self._lock.release() + + def get(self, chanid): + self._lock.acquire() + try: + return self._map.get(chanid, None) + finally: + self._lock.release() + + def delete(self, chanid): + self._lock.acquire() + try: + try: + del self._map[chanid] + except KeyError: + pass + finally: + self._lock.release() + + def values(self): + self._lock.acquire() + try: + return self._map.values() + finally: + self._lock.release() + + def __len__(self): + self._lock.acquire() + try: + return len(self._map) + finally: + self._lock.release() diff --git a/sites/docs/api/transport.rst b/sites/docs/api/transport.rst index 1b54f04e..7c9d9fd1 100644 --- a/sites/docs/api/transport.rst +++ b/sites/docs/api/transport.rst @@ -2,3 +2,4 @@ Transport ========= .. automodule:: paramiko.transport + :member-order: bysource -- cgit v1.2.3 From 0e9a5a4b463fbbc8518e4679850207e31fbd8a0f Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Fri, 21 Feb 2014 14:31:08 -0800 Subject: Move module level docstring into Sphinx docs --- paramiko/__init__.py | 32 -------------------------------- sites/docs/index.rst | 22 ++++++++++++++++++++++ 2 files changed, 22 insertions(+), 32 deletions(-) (limited to 'sites') diff --git a/paramiko/__init__.py b/paramiko/__init__.py index 6e282c63..bfd28f26 100644 --- a/paramiko/__init__.py +++ b/paramiko/__init__.py @@ -16,38 +16,6 @@ # along with Paramiko; if not, write to the Free Software Foundation, Inc., # 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA. -""" -Paramiko (a combination of the esperanto words for "paranoid" and "friend") -is a module for python 2.5 or greater that implements the SSH2 protocol for -secure (encrypted and authenticated) connections to remote machines. Unlike -SSL (aka TLS), the SSH2 protocol does not require hierarchical certificates -signed by a powerful central authority. You may know SSH2 as the protocol that -replaced ``telnet`` and ``rsh`` for secure access to remote shells, but the -protocol also includes the ability to open arbitrary channels to remote -services across an encrypted tunnel. (This is how ``sftp`` works, for example.) - -The high-level client API starts with creation of an `.SSHClient` object. -For more direct control, pass a socket (or socket-like object) to a -`.Transport`, and use `start_server <.Transport.start_server>` or -`start_client <.Transport.start_client>` to negoatite -with the remote host as either a server or client. As a client, you are -responsible for authenticating using a password or private key, and checking -the server's host key. (Key signature and verification is done by paramiko, -but you will need to provide private keys and check that the content of a -public key matches what you expected to see.) As a server, you are -responsible for deciding which users, passwords, and keys to allow, and what -kind of channels to allow. - -Once you have finished, either side may request flow-controlled `channels ` -to the other side, which are python objects that act like sockets, but send and -receive data over the encrypted session. - -Paramiko is written entirely in python (no C or platform-dependent code) and is -released under the GNU Lesser General Public License (LGPL). - -Website: https://github.com/paramiko/paramiko/ -""" - import sys if sys.version_info < (2, 5): diff --git a/sites/docs/index.rst b/sites/docs/index.rst index 98f4069a..87a0f994 100644 --- a/sites/docs/index.rst +++ b/sites/docs/index.rst @@ -10,6 +10,28 @@ please see `the main website `_. API documentation ================= +The high-level client API starts with creation of an `.SSHClient` object. For +more direct control, pass a socket (or socket-like object) to a `.Transport`, +and use `start_server <.Transport.start_server>` or `start_client +<.Transport.start_client>` to negotiate with the remote host as either a server +or client. + +As a client, you are responsible for authenticating using a password or private +key, and checking the server's host key. (Key signature and verification is +done by paramiko, but you will need to provide private keys and check that the +content of a public key matches what you expected to see.) + +As a server, you are responsible for deciding which users, passwords, and keys +to allow, and what kind of channels to allow. + +Once you have finished, either side may request flow-controlled `channels +<.Channel>` to the other side, which are Python objects that act like sockets, +but send and receive data over the encrypted session. + +For details, please see the following tables of contents (which are organized +by area of interest.) + + Core SSH protocol classes ------------------------- -- cgit v1.2.3 From 0b2d523665f3989d9375cd83970400ace0e40336 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Fri, 21 Feb 2014 15:35:22 -0800 Subject: Connect to Python stdlib intersphinx --- sites/docs/conf.py | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'sites') diff --git a/sites/docs/conf.py b/sites/docs/conf.py index c0f51f76..619ff816 100644 --- a/sites/docs/conf.py +++ b/sites/docs/conf.py @@ -9,3 +9,8 @@ extensions.extend(['sphinx.ext.autodoc', 'sphinx.ext.intersphinx']) # Autodoc settings autodoc_default_flags = ['members', 'special-members'] + +# Intersphinx connection to stdlib +intersphinx_mapping = { + 'python': ('http://docs.python.org/2.6', None), +} -- cgit v1.2.3 From 333dd249b01b059f8ecd887a515dd964bfbf7adb Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Fri, 21 Feb 2014 16:37:16 -0800 Subject: Start in on the SFTP section --- paramiko/sftp_attr.py | 4 ++-- paramiko/sftp_client.py | 18 +++++++++--------- sites/docs/api/sftp.rst | 4 ++-- 3 files changed, 13 insertions(+), 13 deletions(-) (limited to 'sites') diff --git a/paramiko/sftp_attr.py b/paramiko/sftp_attr.py index 37cdeba7..b8040399 100644 --- a/paramiko/sftp_attr.py +++ b/paramiko/sftp_attr.py @@ -26,8 +26,8 @@ class SFTPAttributes (object): """ Representation of the attributes of a file (or proxied file) for SFTP in client or server mode. It attemps to mirror the object returned by - ``os.stat`` as closely as possible, so it may have the following fields, - with the same meanings as those returned by an ``os.stat`` object: + `os.stat` as closely as possible, so it may have the following fields, + with the same meanings as those returned by an `os.stat` object: - st_size - st_uid - st_gid diff --git a/paramiko/sftp_client.py b/paramiko/sftp_client.py index d1d62233..b9d8744d 100644 --- a/paramiko/sftp_client.py +++ b/paramiko/sftp_client.py @@ -16,9 +16,6 @@ # along with Paramiko; if not, write to the Free Software Foundation, Inc., # 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA. -""" -Client-mode SFTP support. -""" from binascii import hexlify import errno @@ -49,12 +46,13 @@ def _to_unicode(s): return s -class SFTPClient (BaseSFTP): +class SFTPClient(BaseSFTP): """ - SFTP client object. ``SFTPClient`` is used to open an sftp session across - an open ssh `.Transport` and do remote file operations. + SFTP client object. + + Used to open an SFTP session across an open SSH `.Transport` and perform + remote file operations. """ - def __init__(self, sock): """ Create an SFTP client from an existing `.Channel`. The channel @@ -782,6 +780,8 @@ class SFTPClient (BaseSFTP): return self._cwd + '/' + path -class SFTP (SFTPClient): - "an alias for `.SFTPClient` for backwards compatability" +class SFTP(SFTPClient): + """ + An alias for `.SFTPClient` for backwards compatability. + """ pass diff --git a/sites/docs/api/sftp.rst b/sites/docs/api/sftp.rst index 2eedecf8..c016d73e 100644 --- a/sites/docs/api/sftp.rst +++ b/sites/docs/api/sftp.rst @@ -2,9 +2,9 @@ SFTP ==== .. automodule:: paramiko.sftp -.. automodule:: paramiko.sftp_attr .. automodule:: paramiko.sftp_client +.. automodule:: paramiko.sftp_server +.. automodule:: paramiko.sftp_attr .. automodule:: paramiko.sftp_file .. automodule:: paramiko.sftp_handle -.. automodule:: paramiko.sftp_server .. automodule:: paramiko.sftp_si -- cgit v1.2.3 From 6d9b28c56c81c2d4eb7452f0d986e4e4ec6c3039 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Fri, 21 Feb 2014 16:56:13 -0800 Subject: Remove win_pageant from docs for now :( too many freakin errors --- sites/docs/api/win_pageant.rst | 4 ---- sites/docs/index.rst | 1 - 2 files changed, 5 deletions(-) delete mode 100644 sites/docs/api/win_pageant.rst (limited to 'sites') diff --git a/sites/docs/api/win_pageant.rst b/sites/docs/api/win_pageant.rst deleted file mode 100644 index c48da5c6..00000000 --- a/sites/docs/api/win_pageant.rst +++ /dev/null @@ -1,4 +0,0 @@ -WinPageant support -================== - -.. automodule:: paramiko.win_pageant diff --git a/sites/docs/index.rst b/sites/docs/index.rst index 87a0f994..9e682bb0 100644 --- a/sites/docs/index.rst +++ b/sites/docs/index.rst @@ -50,7 +50,6 @@ Authentication & keys api/agent api/hostkeys api/keys - api/win_pageant Other primary functions -- cgit v1.2.3 From 9ae62eb47a4f7a20eae90a7296ce0a8ecb4923b9 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Fri, 21 Feb 2014 19:15:36 -0800 Subject: Wow there's a lot of SFTP crap. --- paramiko/sftp_attr.py | 19 ++++++++-------- paramiko/sftp_client.py | 58 +++++++++++++++++++++++++------------------------ paramiko/sftp_file.py | 50 +++++++++++++++++++++++------------------- paramiko/sftp_handle.py | 4 ++-- paramiko/sftp_server.py | 6 ++--- paramiko/sftp_si.py | 20 +++++++++-------- sites/docs/api/sftp.rst | 3 +++ 7 files changed, 87 insertions(+), 73 deletions(-) (limited to 'sites') diff --git a/paramiko/sftp_attr.py b/paramiko/sftp_attr.py index b8040399..9b30829c 100644 --- a/paramiko/sftp_attr.py +++ b/paramiko/sftp_attr.py @@ -28,12 +28,13 @@ class SFTPAttributes (object): client or server mode. It attemps to mirror the object returned by `os.stat` as closely as possible, so it may have the following fields, with the same meanings as those returned by an `os.stat` object: - - st_size - - st_uid - - st_gid - - st_mode - - st_atime - - st_mtime + + - ``st_size`` + - ``st_uid`` + - ``st_gid`` + - ``st_mode`` + - ``st_atime`` + - ``st_mtime`` Because SFTP allows flags to have other arbitrary named attributes, these are stored in a dict named ``attr``. Occasionally, the filename is also @@ -61,10 +62,10 @@ class SFTPAttributes (object): def from_stat(cls, obj, filename=None): """ - Create an SFTPAttributes object from an existing ``stat`` object (an - object returned by ``os.stat``). + Create an `.SFTPAttributes` object from an existing ``stat`` object (an + object returned by `os.stat`). - :param obj: an object returned by ``os.stat`` (or equivalent). + :param obj: an object returned by `os.stat` (or equivalent). :type obj: object :param filename: the filename associated with this file. :type filename: str diff --git a/paramiko/sftp_client.py b/paramiko/sftp_client.py index b9d8744d..db8d196f 100644 --- a/paramiko/sftp_client.py +++ b/paramiko/sftp_client.py @@ -1,6 +1,6 @@ # Copyright (C) 2003-2007 Robey Pointer # -# This file is part of paramiko. +# This file is part of Paramiko. # # Paramiko is free software; you can redistribute it and/or modify it under the # terms of the GNU Lesser General Public License as published by the Free @@ -194,16 +194,17 @@ class SFTPClient(BaseSFTP): def open(self, filename, mode='r', bufsize=-1): """ Open a file on the remote server. The arguments are the same as for - Python's built-in ``file`` (aka ``open``). A file-like object is - returned, which closely mimics the behavior of a normal Python file - object, including the ability to be used as a context manager. + Python's built-in `python:file` (aka `python:open`). A file-like + object is returned, which closely mimics the behavior of a normal + Python file object, including the ability to be used as a context + manager. The mode indicates how the file is to be opened: ``'r'`` for reading, - ``'w'`` for writing (truncating an existing file), ``'a'`` for appending, - ``'r+'`` for reading/writing, ``'w+'`` for reading/writing (truncating an - existing file), ``'a+'`` for reading/appending. The Python ``'b'`` flag - is ignored, since SSH treats all files as binary. The ``'U'`` flag is - supported in a compatible way. + ``'w'`` for writing (truncating an existing file), ``'a'`` for + appending, ``'r+'`` for reading/writing, ``'w+'`` for reading/writing + (truncating an existing file), ``'a+'`` for reading/appending. The + Python ``'b'`` flag is ignored, since SSH treats all files as binary. + The ``'U'`` flag is supported in a compatible way. Since 1.5.2, an ``'x'`` flag indicates that the operation should only succeed if the file was created and did not previously exist. This has @@ -222,7 +223,7 @@ class SFTPClient(BaseSFTP): :param bufsize: desired buffering (-1 = default buffer size) :type bufsize: int :return: a file object representing the open file - :rtype: SFTPFile + :rtype: `.SFTPFile` :raises IOError: if the file could not be opened. """ @@ -319,16 +320,16 @@ class SFTPClient(BaseSFTP): contains fewer fields. An SFTP server may return as much or as little info as it wants, so the results may vary from server to server. - Unlike a Python ``stat`` object, the result may not be accessed as a - tuple. This is mostly due to the author's slack factor. + Unlike a Python `python:stat` object, the result may not be accessed as + a tuple. This is mostly due to the author's slack factor. - The fields supported are: ``st_mode``, ``st_size``, ``st_uid``, ``st_gid``, - ``st_atime``, and ``st_mtime``. + The fields supported are: ``st_mode``, ``st_size``, ``st_uid``, + ``st_gid``, ``st_atime``, and ``st_mtime``. :param path: the filename to stat :type path: str :return: an object containing attributes about the given file - :rtype: SFTPAttributes + :rtype: `.SFTPAttributes` """ path = self._adjust_cwd(path) self._log(DEBUG, 'stat(%r)' % path) @@ -346,7 +347,7 @@ class SFTPClient(BaseSFTP): :param path: the filename to stat :type path: str :return: an object containing attributes about the given file - :rtype: SFTPAttributes + :rtype: `.SFTPAttributes` """ path = self._adjust_cwd(path) self._log(DEBUG, 'lstat(%r)' % path) @@ -374,7 +375,7 @@ class SFTPClient(BaseSFTP): def chmod(self, path, mode): """ Change the mode (permissions) of a file. The permissions are - unix-style and identical to those used by Python's ``os.chmod`` + unix-style and identical to those used by Python's `os.chmod` function. :param path: path of the file to change the permissions of @@ -391,7 +392,7 @@ class SFTPClient(BaseSFTP): def chown(self, path, uid, gid): """ Change the owner (``uid``) and group (``gid``) of a file. As with - Python's ``os.chown`` function, you must pass both arguments, so if you + Python's `os.chown` function, you must pass both arguments, so if you only want to change one, use `stat` first to retrieve the current owner and group. @@ -433,9 +434,9 @@ class SFTPClient(BaseSFTP): def truncate(self, path, size): """ - Change the size of the file specified by ``path``. This usually extends - or shrinks the size of the file, just like the ``truncate()`` method on - Python file objects. + Change the size of the file specified by ``path``. This usually + extends or shrinks the size of the file, just like the `~file.truncate` + method on Python file objects. :param path: path of the file to modify :type path: str @@ -498,9 +499,9 @@ class SFTPClient(BaseSFTP): def chdir(self, path): """ Change the "current directory" of this SFTP session. Since SFTP - doesn't really have the concept of a current working directory, this - is emulated by paramiko. Once you use this method to set a working - directory, all operations on this SFTPClient object will be relative + doesn't really have the concept of a current working directory, this is + emulated by Paramiko. Once you use this method to set a working + directory, all operations on this `.SFTPClient` object will be relative to that path. You can pass in ``None`` to stop using a current working directory. @@ -521,7 +522,7 @@ class SFTPClient(BaseSFTP): def getcwd(self): """ Return the "current working directory" for this SFTP session, as - emulated by paramiko. If no directory has been set with `chdir`, + emulated by Paramiko. If no directory has been set with `chdir`, this method will return ``None``. :return: the current working directory on the server, or ``None`` @@ -534,7 +535,8 @@ class SFTPClient(BaseSFTP): def putfo(self, fl, remotepath, file_size=0, callback=None, confirm=True): """ Copy the contents of an open file object (``fl``) to the SFTP server as - ``remotepath``. Any exception raised by operations will be passed through. + ``remotepath``. Any exception raised by operations will be passed + through. The SFTP operations use pipelining for speed. @@ -555,7 +557,7 @@ class SFTPClient(BaseSFTP): :return: an object containing attributes about the given file (since 1.7.4) - :rtype: SFTPAttributes + :rtype: `.SFTPAttributes` .. versionadded:: 1.4 """ @@ -603,7 +605,7 @@ class SFTPClient(BaseSFTP): :return: an object containing attributes about the given file (since 1.7.4) - :rtype: SFTPAttributes + :rtype: `.SFTPAttributes` .. versionadded:: 1.4 """ diff --git a/paramiko/sftp_file.py b/paramiko/sftp_file.py index fa026ec5..068ca1a1 100644 --- a/paramiko/sftp_file.py +++ b/paramiko/sftp_file.py @@ -17,7 +17,7 @@ # 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA. """ -`.SFTPFile` +SFTP file object """ from __future__ import with_statement @@ -64,6 +64,9 @@ class SFTPFile (BufferedFile): self._close(async=True) def close(self): + """ + Close the file. + """ self._close(async=False) def _close(self, async=False): @@ -183,10 +186,11 @@ class SFTPFile (BufferedFile): Set a timeout on read/write operations on the underlying socket or ssh `.Channel`. - .. seealso:: `Channel.settimeout` :param timeout: seconds to wait for a pending read/write operation before raising ``socket.timeout``, or ``None`` for no timeout :type timeout: float + + .. seealso:: `.Channel.settimeout` """ self.sftp.sock.settimeout(timeout) @@ -195,8 +199,9 @@ class SFTPFile (BufferedFile): Returns the timeout in seconds (as a float) associated with the socket or ssh `.Channel` used for this file. - .. seealso:: `Channel.gettimeout` :rtype: float + + .. seealso:: `.Channel.gettimeout` """ return self.sftp.sock.gettimeout() @@ -205,10 +210,11 @@ class SFTPFile (BufferedFile): Set blocking or non-blocking mode on the underiying socket or ssh `.Channel`. - .. seealso:: `Channel.setblocking` - :param blocking: 0 to set non-blocking mode; non-0 to set blocking - mode. + :param blocking: + 0 to set non-blocking mode; non-0 to set blocking mode. :type blocking: int + + .. seealso:: `.Channel.setblocking` """ self.sftp.sock.setblocking(blocking) @@ -226,11 +232,11 @@ class SFTPFile (BufferedFile): def stat(self): """ Retrieve information about this file from the remote system. This is - exactly like `SFTP.stat`, except that it operates on an already-open - file. + exactly like `.SFTPClient.stat`, except that it operates on an + already-open file. :return: an object containing attributes about this file. - :rtype: SFTPAttributes + :rtype: `.SFTPAttributes` """ t, msg = self.sftp._request(CMD_FSTAT, self.handle) if t != CMD_ATTRS: @@ -240,7 +246,7 @@ class SFTPFile (BufferedFile): def chmod(self, mode): """ Change the mode (permissions) of this file. The permissions are - unix-style and identical to those used by Python's ``os.chmod`` + unix-style and identical to those used by Python's `os.chmod` function. :param mode: new permissions @@ -254,7 +260,7 @@ class SFTPFile (BufferedFile): def chown(self, uid, gid): """ Change the owner (``uid``) and group (``gid``) of this file. As with - Python's ``os.chown`` function, you must pass both arguments, so if you + Python's `os.chown` function, you must pass both arguments, so if you only want to change one, use `stat` first to retrieve the current owner and group. @@ -341,12 +347,12 @@ class SFTPFile (BufferedFile): concatenated together :rtype: str - .. note:: Many (most?) servers don't support this extension yet. - :raises IOError: if the server doesn't support the "check-file" extension, or possibly doesn't support the hash algorithm requested + .. note:: Many (most?) servers don't support this extension yet. + .. versionadded:: 1.4 """ t, msg = self.sftp._request(CMD_EXTENDED, 'check-file', self.handle, @@ -360,11 +366,11 @@ class SFTPFile (BufferedFile): """ Turn on/off the pipelining of write operations to this file. When pipelining is on, paramiko won't wait for the server response after - each write operation. Instead, they're collected as they come in. - At the first non-write operation (including `close`), all remaining + each write operation. Instead, they're collected as they come in. At + the first non-write operation (including `.close`), all remaining server responses are collected. This means that if there was an error - with one of your later writes, an exception might be thrown from - within `close` instead of `write`. + with one of your later writes, an exception might be thrown from within + `.close` instead of `.write`. By default, files are not pipelined. @@ -378,14 +384,14 @@ class SFTPFile (BufferedFile): def prefetch(self): """ - Pre-fetch the remaining contents of this file in anticipation of - future `read` calls. If reading the entire file, pre-fetching can + Pre-fetch the remaining contents of this file in anticipation of future + `.read` calls. If reading the entire file, pre-fetching can dramatically improve the download speed by avoiding roundtrip latency. The file's contents are incrementally buffered in a background thread. - The prefetched data is stored in a buffer until read via the `read` + The prefetched data is stored in a buffer until read via the `.read` method. Once data has been read, it's removed from the buffer. The - data may be read in a random order (using `seek`); chunks of the + data may be read in a random order (using `.seek`); chunks of the buffer that haven't been read will continue to be buffered. .. versionadded:: 1.5.1 @@ -404,7 +410,7 @@ class SFTPFile (BufferedFile): def readv(self, chunks): """ Read a set of blocks from the file by (offset, length). This is more - efficient than doing a series of `seek` and `read` calls, since the + efficient than doing a series of `.seek` and `.read` calls, since the prefetch machinery is used to retrieve all the requested blocks at once. diff --git a/paramiko/sftp_handle.py b/paramiko/sftp_handle.py index 7e1389a2..6965fd65 100644 --- a/paramiko/sftp_handle.py +++ b/paramiko/sftp_handle.py @@ -41,7 +41,7 @@ class SFTPHandle (object): SFTP. If ``flags`` is passed in, it's used to determine if the file is open in append mode. - :param flags: optional flags as passed to `SFTPServerInterface.open` + :param flags: optional flags as passed to `.SFTPServerInterface.open` :type flags: int """ self.__flags = flags @@ -149,7 +149,7 @@ class SFTPHandle (object): def stat(self): """ Return an `.SFTPAttributes` object referring to this open file, or an - error code. This is equivalent to `SFTPServerInterface.stat`, except + error code. This is equivalent to `.SFTPServerInterface.stat`, except it's called on an open file instead of a path. :return: an attributes object for the given file, or an SFTP error diff --git a/paramiko/sftp_server.py b/paramiko/sftp_server.py index c7e80c1c..9b7ed5ca 100644 --- a/paramiko/sftp_server.py +++ b/paramiko/sftp_server.py @@ -42,7 +42,7 @@ class SFTPServer (BaseSFTP, SubsystemHandler): """ Server-side SFTP subsystem support. Since this is a `.SubsystemHandler`, it can be (and is meant to be) set as the handler for ``"sftp"`` requests. - Use `Transport.set_subsystem_handler` to activate this class. + Use `.Transport.set_subsystem_handler` to activate this class. """ def __init__(self, channel, name, server, sftp_si=SFTPServerInterface, *largs, **kwargs): @@ -50,7 +50,7 @@ class SFTPServer (BaseSFTP, SubsystemHandler): The constructor for SFTPServer is meant to be called from within the `.Transport` as a subsystem handler. ``server`` and any additional parameters or keyword parameters are passed from the original call to - `Transport.set_subsystem_handler`. + `.Transport.set_subsystem_handler`. :param channel: channel passed from the `.Transport`. :type channel: `.Channel` @@ -128,7 +128,7 @@ class SFTPServer (BaseSFTP, SubsystemHandler): :param e: an errno code, as from ``OSError.errno``. :type e: int - :return: an SFTP error code like `.SFTP_NO_SUCH_FILE`. + :return: an SFTP error code like ``SFTP_NO_SUCH_FILE``. :rtype: int """ if e == errno.EACCES: diff --git a/paramiko/sftp_si.py b/paramiko/sftp_si.py index b2debd3d..ead483a0 100644 --- a/paramiko/sftp_si.py +++ b/paramiko/sftp_si.py @@ -17,7 +17,7 @@ # 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA. """ -`.SFTPServerInterface` is an interface to override for SFTP server support. +An interface to override for SFTP server support. """ import os @@ -64,7 +64,7 @@ class SFTPServerInterface (object): """ The SFTP server session has just ended, either cleanly or via an exception. This method is meant to be overridden to perform any - necessary cleanup before this ``SFTPServerInterface`` object is + necessary cleanup before this `.SFTPServerInterface` object is destroyed. """ pass @@ -105,7 +105,7 @@ class SFTPServerInterface (object): :param attr: requested attributes of the file if it is newly created. :type attr: `.SFTPAttributes` :return: a new `.SFTPHandle` or error code. - :rtype `.SFTPHandle` + :rtype: `.SFTPHandle` """ return SFTP_OP_UNSUPPORTED @@ -120,7 +120,7 @@ class SFTPServerInterface (object): ``os.stat``. In addition, each object should have its ``filename`` field filled in, since this is important to a directory listing and not normally present in ``os.stat`` results. The method - `SFTPAttributes.from_stat` will usually do what you want. + `.SFTPAttributes.from_stat` will usually do what you want. In case of an error, you should return one of the ``SFTP_*`` error codes, such as `.SFTP_PERMISSION_DENIED`. @@ -131,11 +131,13 @@ class SFTPServerInterface (object): `.SFTPAttributes` objects. :rtype: list of `.SFTPAttributes` or error code - .. note:: You should normalize the given ``path`` first (see the - ``os.path`` module) and check appropriate permissions before returning - the list of files. Be careful of malicious clients attempting to use - relative paths to escape restricted folders, if you're doing a direct - translation from the SFTP server path to your local filesystem. + .. note:: + You should normalize the given ``path`` first (see the `os.path` + module) and check appropriate permissions before returning the list + of files. Be careful of malicious clients attempting to use + relative paths to escape restricted folders, if you're doing a + direct translation from the SFTP server path to your local + filesystem. """ return SFTP_OP_UNSUPPORTED diff --git a/sites/docs/api/sftp.rst b/sites/docs/api/sftp.rst index c016d73e..956eada2 100644 --- a/sites/docs/api/sftp.rst +++ b/sites/docs/api/sftp.rst @@ -6,5 +6,8 @@ SFTP .. automodule:: paramiko.sftp_server .. automodule:: paramiko.sftp_attr .. automodule:: paramiko.sftp_file + :inherited-members: + :no-special-members: + :show-inheritance: .. automodule:: paramiko.sftp_handle .. automodule:: paramiko.sftp_si -- cgit v1.2.3 From c23579526b4a3c05e6d20bf92074ea0c8c37751d Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Mon, 24 Feb 2014 09:49:30 -0800 Subject: Tweak order of System doc page --- paramiko/server.py | 84 +++++++++++++++++++++++------------------------ sites/docs/api/server.rst | 1 + 2 files changed, 43 insertions(+), 42 deletions(-) (limited to 'sites') diff --git a/paramiko/server.py b/paramiko/server.py index 9ff7243b..e7d37849 100644 --- a/paramiko/server.py +++ b/paramiko/server.py @@ -25,48 +25,6 @@ from paramiko.common import * from paramiko import util -class InteractiveQuery (object): - """ - A query (set of prompts) for a user during interactive authentication. - """ - - def __init__(self, name='', instructions='', *prompts): - """ - Create a new interactive query to send to the client. The name and - instructions are optional, but are generally displayed to the end - user. A list of prompts may be included, or they may be added via - the `add_prompt` method. - - :param name: name of this query - :type name: str - :param instructions: user instructions (usually short) about this query - :type instructions: str - :param prompts: one or more authentication prompts - :type prompts: str - """ - self.name = name - self.instructions = instructions - self.prompts = [] - for x in prompts: - if (type(x) is str) or (type(x) is unicode): - self.add_prompt(x) - else: - self.add_prompt(x[0], x[1]) - - def add_prompt(self, prompt, echo=True): - """ - Add a prompt to this query. The prompt should be a (reasonably short) - string. Multiple prompts can be added to the same query. - - :param prompt: the user prompt - :type prompt: str - :param echo: ``True`` (default) if the user's response should be echoed; - ``False`` if not (for a password or similar) - :type echo: bool - """ - self.prompts.append((prompt, echo)) - - class ServerInterface (object): """ This class defines an interface for controlling the behavior of paramiko @@ -551,6 +509,48 @@ class ServerInterface (object): return OPEN_FAILED_ADMINISTRATIVELY_PROHIBITED +class InteractiveQuery (object): + """ + A query (set of prompts) for a user during interactive authentication. + """ + + def __init__(self, name='', instructions='', *prompts): + """ + Create a new interactive query to send to the client. The name and + instructions are optional, but are generally displayed to the end + user. A list of prompts may be included, or they may be added via + the `add_prompt` method. + + :param name: name of this query + :type name: str + :param instructions: user instructions (usually short) about this query + :type instructions: str + :param prompts: one or more authentication prompts + :type prompts: str + """ + self.name = name + self.instructions = instructions + self.prompts = [] + for x in prompts: + if (type(x) is str) or (type(x) is unicode): + self.add_prompt(x) + else: + self.add_prompt(x[0], x[1]) + + def add_prompt(self, prompt, echo=True): + """ + Add a prompt to this query. The prompt should be a (reasonably short) + string. Multiple prompts can be added to the same query. + + :param prompt: the user prompt + :type prompt: str + :param echo: ``True`` (default) if the user's response should be echoed; + ``False`` if not (for a password or similar) + :type echo: bool + """ + self.prompts.append((prompt, echo)) + + class SubsystemHandler (threading.Thread): """ Handler for a subsytem in server mode. If you create a subclass of this diff --git a/sites/docs/api/server.rst b/sites/docs/api/server.rst index 7519ae99..ea854544 100644 --- a/sites/docs/api/server.rst +++ b/sites/docs/api/server.rst @@ -2,3 +2,4 @@ Server implementation ===================== .. automodule:: paramiko.server + :member-order: bysource -- cgit v1.2.3 From 24cc59b64d4325a42f8992c7c916ace18bbcf960 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Mon, 24 Feb 2014 10:01:03 -0800 Subject: Reorder config doc --- paramiko/config.py | 110 +++++++++++++++++++++++----------------------- sites/docs/api/config.rst | 1 + 2 files changed, 56 insertions(+), 55 deletions(-) (limited to 'sites') diff --git a/paramiko/config.py b/paramiko/config.py index 6f3bbdfc..ea978017 100644 --- a/paramiko/config.py +++ b/paramiko/config.py @@ -18,7 +18,7 @@ # 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA. """ -`.SSHConfig`. +Configuration file (aka ``ssh_config``) support. """ import fnmatch @@ -30,60 +30,6 @@ SSH_PORT = 22 proxy_re = re.compile(r"^(proxycommand)\s*=*\s*(.*)", re.I) -class LazyFqdn(object): - """ - Returns the host's fqdn on request as string. - """ - - def __init__(self, config, host=None): - self.fqdn = None - self.config = config - self.host = host - - def __str__(self): - if self.fqdn is None: - # - # If the SSH config contains AddressFamily, use that when - # determining the local host's FQDN. Using socket.getfqdn() from - # the standard library is the most general solution, but can - # result in noticeable delays on some platforms when IPv6 is - # misconfigured or not available, as it calls getaddrinfo with no - # address family specified, so both IPv4 and IPv6 are checked. - # - - # Handle specific option - fqdn = None - address_family = self.config.get('addressfamily', 'any').lower() - if address_family != 'any': - try: - family = socket.AF_INET if address_family == 'inet' \ - else socket.AF_INET6 - results = socket.getaddrinfo( - self.host, - None, - family, - socket.SOCK_DGRAM, - socket.IPPROTO_IP, - socket.AI_CANONNAME - ) - for res in results: - af, socktype, proto, canonname, sa = res - if canonname and '.' in canonname: - fqdn = canonname - break - # giaerror -> socket.getaddrinfo() can't resolve self.host - # (which is from socket.gethostname()). Fall back to the - # getfqdn() call below. - except socket.gaierror: - pass - # Handle 'any' / unspecified - if fqdn is None: - fqdn = socket.getfqdn() - # Cache - self.fqdn = fqdn - return self.fqdn - - class SSHConfig (object): """ Representation of config information as stored in the format used by @@ -264,3 +210,57 @@ class SSHConfig (object): else: config[k] = config[k].replace(find, str(replace)) return config + + +class LazyFqdn(object): + """ + Returns the host's fqdn on request as string. + """ + + def __init__(self, config, host=None): + self.fqdn = None + self.config = config + self.host = host + + def __str__(self): + if self.fqdn is None: + # + # If the SSH config contains AddressFamily, use that when + # determining the local host's FQDN. Using socket.getfqdn() from + # the standard library is the most general solution, but can + # result in noticeable delays on some platforms when IPv6 is + # misconfigured or not available, as it calls getaddrinfo with no + # address family specified, so both IPv4 and IPv6 are checked. + # + + # Handle specific option + fqdn = None + address_family = self.config.get('addressfamily', 'any').lower() + if address_family != 'any': + try: + family = socket.AF_INET if address_family == 'inet' \ + else socket.AF_INET6 + results = socket.getaddrinfo( + self.host, + None, + family, + socket.SOCK_DGRAM, + socket.IPPROTO_IP, + socket.AI_CANONNAME + ) + for res in results: + af, socktype, proto, canonname, sa = res + if canonname and '.' in canonname: + fqdn = canonname + break + # giaerror -> socket.getaddrinfo() can't resolve self.host + # (which is from socket.gethostname()). Fall back to the + # getfqdn() call below. + except socket.gaierror: + pass + # Handle 'any' / unspecified + if fqdn is None: + fqdn = socket.getfqdn() + # Cache + self.fqdn = fqdn + return self.fqdn diff --git a/sites/docs/api/config.rst b/sites/docs/api/config.rst index 6f9d3ce3..afb004c9 100644 --- a/sites/docs/api/config.rst +++ b/sites/docs/api/config.rst @@ -2,3 +2,4 @@ Configuration ============= .. automodule:: paramiko.config + :member-order: bysource -- cgit v1.2.3 From 4bcac18d17b62d3553f4fd91c9e904c1d5808cfe Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Mon, 24 Feb 2014 10:08:46 -0800 Subject: Host key docs (order + tweaks) --- paramiko/hostkeys.py | 163 +++++++++++++++++++++----------------------- sites/docs/api/hostkeys.rst | 1 + 2 files changed, 80 insertions(+), 84 deletions(-) (limited to 'sites') diff --git a/paramiko/hostkeys.py b/paramiko/hostkeys.py index 1eed350a..ceb9051f 100644 --- a/paramiko/hostkeys.py +++ b/paramiko/hostkeys.py @@ -16,9 +16,6 @@ # along with Paramiko; if not, write to the Free Software Foundation, Inc., # 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA. -""" -`.HostKeys` -""" import base64 import binascii @@ -31,95 +28,21 @@ from paramiko.rsakey import RSAKey from paramiko.util import get_logger, constant_time_bytes_eq -class InvalidHostKey(Exception): - - def __init__(self, line, exc): - self.line = line - self.exc = exc - self.args = (line, exc) - - -class HostKeyEntry: - """ - Representation of a line in an OpenSSH-style "known hosts" file. - """ - - def __init__(self, hostnames=None, key=None): - self.valid = (hostnames is not None) and (key is not None) - self.hostnames = hostnames - self.key = key - - def from_line(cls, line, lineno=None): - """ - Parses the given line of text to find the names for the host, - the type of key, and the key data. The line is expected to be in the - format used by the openssh known_hosts file. - - Lines are expected to not have leading or trailing whitespace. - We don't bother to check for comments or empty lines. All of - that should be taken care of before sending the line to us. - - :param line: a line from an OpenSSH known_hosts file - :type line: str - """ - log = get_logger('paramiko.hostkeys') - fields = line.split(' ') - if len(fields) < 3: - # Bad number of fields - log.info("Not enough fields found in known_hosts in line %s (%r)" % - (lineno, line)) - return None - fields = fields[:3] - - names, keytype, key = fields - names = names.split(',') - - # Decide what kind of key we're looking at and create an object - # to hold it accordingly. - try: - if keytype == 'ssh-rsa': - key = RSAKey(data=base64.decodestring(key)) - elif keytype == 'ssh-dss': - key = DSSKey(data=base64.decodestring(key)) - else: - log.info("Unable to handle key of type %s" % (keytype,)) - return None - except binascii.Error, e: - raise InvalidHostKey(line, e) - - return cls(names, key) - from_line = classmethod(from_line) - - def to_line(self): - """ - Returns a string in OpenSSH known_hosts file format, or None if - the object is not in a valid state. A trailing newline is - included. - """ - if self.valid: - return '%s %s %s\n' % (','.join(self.hostnames), self.key.get_name(), - self.key.get_base64()) - return None - - def __repr__(self): - return '' % (self.hostnames, self.key) - - class HostKeys (UserDict.DictMixin): """ - Representation of an openssh-style "known hosts" file. Host keys can be + Representation of an OpenSSH-style "known hosts" file. Host keys can be read from one or more files, and then individual hosts can be looked up to verify server keys during SSH negotiation. - A HostKeys object can be treated like a dict; any dict lookup is equivalent - to calling `lookup`. + A `.HostKeys` object can be treated like a dict; any dict lookup is + equivalent to calling `lookup`. .. versionadded:: 1.5.3 """ def __init__(self, filename=None): """ - Create a new HostKeys object, optionally loading keys from an openssh + Create a new HostKeys object, optionally loading keys from an OpenSSH style host-key file. :param filename: filename to load host keys from, or ``None`` @@ -150,7 +73,7 @@ class HostKeys (UserDict.DictMixin): def load(self, filename): """ - Read a file of known SSH host keys, in the format used by openssh. + Read a file of known SSH host keys, in the format used by OpenSSH. This type of file unfortunately doesn't exist on Windows, but on posix, it will usually be stored in ``os.path.expanduser("~/.ssh/known_hosts")``. @@ -181,7 +104,7 @@ class HostKeys (UserDict.DictMixin): def save(self, filename): """ - Save host keys into a file, in the format used by openssh. The order of + Save host keys into a file, in the format used by OpenSSH. The order of keys in the file will be preserved when possible (if these keys were loaded from a file originally). The single exception is that combined lines will be split into individual key lines, which is arguably a bug. @@ -314,7 +237,7 @@ class HostKeys (UserDict.DictMixin): def hash_host(hostname, salt=None): """ - Return a "hashed" form of the hostname, as used by openssh when storing + Return a "hashed" form of the hostname, as used by OpenSSH when storing hashed hostnames in the known_hosts file. :param hostname: the hostname to hash @@ -336,3 +259,75 @@ class HostKeys (UserDict.DictMixin): return hostkey.replace('\n', '') hash_host = staticmethod(hash_host) + +class InvalidHostKey(Exception): + def __init__(self, line, exc): + self.line = line + self.exc = exc + self.args = (line, exc) + + +class HostKeyEntry: + """ + Representation of a line in an OpenSSH-style "known hosts" file. + """ + + def __init__(self, hostnames=None, key=None): + self.valid = (hostnames is not None) and (key is not None) + self.hostnames = hostnames + self.key = key + + def from_line(cls, line, lineno=None): + """ + Parses the given line of text to find the names for the host, + the type of key, and the key data. The line is expected to be in the + format used by the OpenSSH known_hosts file. + + Lines are expected to not have leading or trailing whitespace. + We don't bother to check for comments or empty lines. All of + that should be taken care of before sending the line to us. + + :param line: a line from an OpenSSH known_hosts file + :type line: str + """ + log = get_logger('paramiko.hostkeys') + fields = line.split(' ') + if len(fields) < 3: + # Bad number of fields + log.info("Not enough fields found in known_hosts in line %s (%r)" % + (lineno, line)) + return None + fields = fields[:3] + + names, keytype, key = fields + names = names.split(',') + + # Decide what kind of key we're looking at and create an object + # to hold it accordingly. + try: + if keytype == 'ssh-rsa': + key = RSAKey(data=base64.decodestring(key)) + elif keytype == 'ssh-dss': + key = DSSKey(data=base64.decodestring(key)) + else: + log.info("Unable to handle key of type %s" % (keytype,)) + return None + except binascii.Error, e: + raise InvalidHostKey(line, e) + + return cls(names, key) + from_line = classmethod(from_line) + + def to_line(self): + """ + Returns a string in OpenSSH known_hosts file format, or None if + the object is not in a valid state. A trailing newline is + included. + """ + if self.valid: + return '%s %s %s\n' % (','.join(self.hostnames), self.key.get_name(), + self.key.get_base64()) + return None + + def __repr__(self): + return '' % (self.hostnames, self.key) diff --git a/sites/docs/api/hostkeys.rst b/sites/docs/api/hostkeys.rst index 0859fbed..770652fd 100644 --- a/sites/docs/api/hostkeys.rst +++ b/sites/docs/api/hostkeys.rst @@ -2,3 +2,4 @@ Host keys / ``known_hosts`` files ================================= .. automodule:: paramiko.hostkeys + :member-order: bysource -- cgit v1.2.3 From 9ae46dcbfaab42b450db410eecd8e7e94183f1b8 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Mon, 24 Feb 2014 17:00:53 -0800 Subject: Fix up AgentSSH vs Agent classes/docstrings, sigh --- paramiko/agent.py | 29 +++++++---------------------- sites/docs/api/agent.rst | 2 ++ 2 files changed, 9 insertions(+), 22 deletions(-) (limited to 'sites') diff --git a/paramiko/agent.py b/paramiko/agent.py index f5b116ca..302d31ec 100644 --- a/paramiko/agent.py +++ b/paramiko/agent.py @@ -17,7 +17,7 @@ # 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA. """ -SSH Agent interface for Unix clients. +SSH Agent interface """ import os @@ -42,16 +42,6 @@ SSH2_AGENTC_REQUEST_IDENTITIES, SSH2_AGENT_IDENTITIES_ANSWER, \ class AgentSSH(object): - """ - Client interface for using private keys from an SSH agent running on the - local machine. If an SSH agent is running, this class can be used to - connect to it and retreive `.PKey` objects which can be used when - attempting to authenticate to remote SSH servers. - - Because the SSH agent protocol uses environment variables and unix-domain - sockets, this probably doesn't work on Windows. It does work on most - posix platforms though (Linux and MacOS X, for example). - """ def __init__(self): self._conn = None self._keys = () @@ -318,19 +308,14 @@ class Agent(AgentSSH): connect to it and retreive `.PKey` objects which can be used when attempting to authenticate to remote SSH servers. - Because the SSH agent protocol uses environment variables and unix-domain - sockets, this probably doesn't work on Windows. It does work on most - posix platforms though (Linux and MacOS X, for example). + Upon initialization, a session with the local machine's SSH agent is + opened, if one is running. If no agent is running, initialization will + succeed, but `get_keys` will return an empty tuple. + + :raises SSHException: + if an SSH agent is found, but speaks an incompatible protocol """ def __init__(self): - """ - Open a session with the local machine's SSH agent, if one is running. - If no agent is running, initialization will succeed, but `get_keys` - will return an empty tuple. - - :raises SSHException: if an SSH agent is found, but speaks an - incompatible protocol - """ AgentSSH.__init__(self) if ('SSH_AUTH_SOCK' in os.environ) and (sys.platform != 'win32'): diff --git a/sites/docs/api/agent.rst b/sites/docs/api/agent.rst index 789f7b1d..3b614a82 100644 --- a/sites/docs/api/agent.rst +++ b/sites/docs/api/agent.rst @@ -2,3 +2,5 @@ SSH Agents ========== .. automodule:: paramiko.agent + :inherited-members: + :no-special-members: -- cgit v1.2.3 From 83f09e634f4e57707c8423423f5cb8ad74d731bd Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Mon, 3 Mar 2014 17:30:15 -0800 Subject: Changelog re #256 --- sites/www/changelog.rst | 3 +++ 1 file changed, 3 insertions(+) (limited to 'sites') diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst index fa58c5f6..fa43a379 100644 --- a/sites/www/changelog.rst +++ b/sites/www/changelog.rst @@ -2,6 +2,9 @@ Changelog ========= +* :support:`256` Convert API documentation to Sphinx, yielding a new API + docs website to replace the old Epydoc one. Thanks to Olle Lundberg for the + initial conversion work. * :bug:`-` Use constant-time hash comparison operations where possible, to protect against `timing-based attacks `_. Thanks to Alex Gaynor -- cgit v1.2.3 From 056323979d7a2a5623bc2c3845fde9888093b4f2 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Mon, 3 Mar 2014 18:22:33 -0800 Subject: Re-enable Intersphinx from www -> docs --- sites/www/conf.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'sites') diff --git a/sites/www/conf.py b/sites/www/conf.py index 481acdff..1c6c9254 100644 --- a/sites/www/conf.py +++ b/sites/www/conf.py @@ -24,10 +24,10 @@ extensions.append('sphinx.ext.intersphinx') target = join(dirname(__file__), '..', 'docs', '_build') if os.environ.get('READTHEDOCS') == 'True': # TODO: switch to docs.paramiko.org post go-live of sphinx API docs - target = 'http://paramiko-docs.readthedocs.org/en/latest/' -#intersphinx_mapping = { -# 'docs': (target, None), -#} + target = 'http://docs.paramiko.org/en/latest/' +intersphinx_mapping = { + 'docs': (target, None), +} # Sister-site links to API docs html_theme_options['extra_nav_links'] = { -- cgit v1.2.3 From f2958401915935539eaf87f505e0dadfc8debc33 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Tue, 4 Mar 2014 15:45:01 -0800 Subject: Semi no-op fix to test RTD hooks --- sites/docs/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'sites') diff --git a/sites/docs/index.rst b/sites/docs/index.rst index 9e682bb0..f336b393 100644 --- a/sites/docs/index.rst +++ b/sites/docs/index.rst @@ -4,7 +4,7 @@ Welcome to Paramiko's documentation! This site covers Paramiko's usage & API documentation. For basic info on what Paramiko is, including its public changelog & how the project is maintained, -please see `the main website `_. +please see `the main project website `_. API documentation -- cgit v1.2.3 From 798e3689dda432e711ca997bd2f18b8b2dec272f Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Tue, 4 Mar 2014 16:16:29 -0800 Subject: Note Sphinx docs issue was backported --- sites/www/changelog.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'sites') diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst index fa43a379..fee5a962 100644 --- a/sites/www/changelog.rst +++ b/sites/www/changelog.rst @@ -2,9 +2,9 @@ Changelog ========= -* :support:`256` Convert API documentation to Sphinx, yielding a new API - docs website to replace the old Epydoc one. Thanks to Olle Lundberg for the - initial conversion work. +* :support:`256 backported` Convert API documentation to Sphinx, yielding a new + API docs website to replace the old Epydoc one. Thanks to Olle Lundberg for + the initial conversion work. * :bug:`-` Use constant-time hash comparison operations where possible, to protect against `timing-based attacks `_. Thanks to Alex Gaynor -- cgit v1.2.3 From 7a776b1757e65611460065adc8fc784b1a9525b4 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Tue, 4 Mar 2014 17:43:30 -0800 Subject: Testing out intersphinx in changelog --- sites/www/changelog.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'sites') diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst index 0e168370..0a170a1a 100644 --- a/sites/www/changelog.rst +++ b/sites/www/changelog.rst @@ -13,7 +13,8 @@ Changelog * :release:`1.11.4 <2014-02-14>` * :release:`1.10.6 <2014-02-14>` * :feature:`58` Allow client code to access the stored SSH server banner via - ``Transport.get_banner()``. Thanks to ``@Jhoanor`` for the patch. + `Transport.get_banner `. Thanks to + ``@Jhoanor`` for the patch. * :bug:`252` (`Fabric #1020 `_) Enhanced the implementation of ``ProxyCommand`` to avoid a deadlock/hang condition that frequently occurs at ``Transport`` shutdown time. Thanks to -- cgit v1.2.3 From 073c71a8223ff77cacd8c555ef63ce24f0c3d50c Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Fri, 7 Mar 2014 18:46:40 -0800 Subject: Attempt to fix docs for py3 --- sites/shared_conf.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'sites') diff --git a/sites/shared_conf.py b/sites/shared_conf.py index 86ecdfe8..52cec938 100644 --- a/sites/shared_conf.py +++ b/sites/shared_conf.py @@ -31,9 +31,9 @@ html_sidebars = { } # Regular settings -project = u'Paramiko' +project = 'Paramiko' year = datetime.now().year -copyright = u'%d Jeff Forcier' % year +copyright = '%d Jeff Forcier' % year master_doc = 'index' templates_path = ['_templates'] exclude_trees = ['_build'] -- cgit v1.2.3 From 8463053fa5602efeeffe4ef205bbd5f9ab3da50f Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Thu, 13 Mar 2014 11:15:20 -0700 Subject: Add changelog re #16 --- sites/www/changelog.rst | 7 +++++++ 1 file changed, 7 insertions(+) (limited to 'sites') diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst index 0a170a1a..c9c14492 100644 --- a/sites/www/changelog.rst +++ b/sites/www/changelog.rst @@ -2,6 +2,13 @@ Changelog ========= +* :feature:`16` **Python 3 support!** Our test suite passes under Python 3, and + it (& Fabric's test suite) continues to pass under Python 2. + + The merged code was built on many contributors' efforts, both code & + feedback. In no particular order, we thank Daniel Goertzen, Ivan Kolodyazhny, + Tomi Pieviläinen, Jason R. Coombs, Jan N. Schulze, ``@Lazik``, Dorian Pula, + Scott Maxwell, Tshepang Lekhonkhobe, Aaron Meurer, and Dave Halter. * :support:`256 backported` Convert API documentation to Sphinx, yielding a new API docs website to replace the old Epydoc one. Thanks to Olle Lundberg for the initial conversion work. -- cgit v1.2.3 From 120071283d5490f1f942be764c1284b93cddcf0c Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Thu, 13 Mar 2014 11:15:34 -0700 Subject: Fix accidental Markdown formatting miss for an older entry --- sites/www/changelog.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'sites') diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst index c9c14492..5cd718eb 100644 --- a/sites/www/changelog.rst +++ b/sites/www/changelog.rst @@ -46,10 +46,10 @@ Changelog * :release:`1.12.0 <2013-09-27>` * :release:`1.11.2 <2013-09-27>` * :release:`1.10.4 <2013-09-27>` -* :feature:`152` Add tentative support for ECDSA keys. *This adds the ecdsa - module as a new dependency of Paramiko.* The module is available at - [warner/python-ecdsa on Github](https://github.com/warner/python-ecdsa) and - [ecdsa on PyPI](https://pypi.python.org/pypi/ecdsa). +* :feature:`152` Add tentative support for ECDSA keys. **This adds the ecdsa + module as a new dependency of Paramiko.** The module is available at + `warner/python-ecdsa on Github `_ and + `ecdsa on PyPI `_. * Note that you might still run into problems with key negotiation -- Paramiko picks the first key that the server offers, which might not be -- cgit v1.2.3 From b0b6a827b96453cfe9bddb343f94c5c2f4243f7b Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Thu, 13 Mar 2014 21:05:32 -0700 Subject: Update docs to reflect Python 2.6+, 3.3+ compat --- sites/www/index.rst | 2 +- sites/www/installing.rst | 34 +++------------------------------- 2 files changed, 4 insertions(+), 32 deletions(-) (limited to 'sites') diff --git a/sites/www/index.rst b/sites/www/index.rst index 7fefedd2..a8e72624 100644 --- a/sites/www/index.rst +++ b/sites/www/index.rst @@ -1,7 +1,7 @@ Welcome to Paramiko! ==================== -Paramiko is a Python (2.5+) implementation of the SSHv2 protocol [#]_, +Paramiko is a Python (2.6+, 3.3+) implementation of the SSHv2 protocol [#]_, providing both client and server functionality. While it leverages a Python C extension for low level cryptography (`PyCrypto `_), Paramiko itself is a pure Python interface around SSH networking concepts. diff --git a/sites/www/installing.rst b/sites/www/installing.rst index 0d4dc1ac..955a0a59 100644 --- a/sites/www/installing.rst +++ b/sites/www/installing.rst @@ -14,9 +14,9 @@ via `pip `_:: Users who want the bleeding edge can install the development version via ``pip install paramiko==dev``. -We currently support **Python 2.5/2.6/2.7**, with support for Python 3 coming -soon. Users on Python 2.4 or older are urged to upgrade. Paramiko *may* work on -Python 2.4 still, but there is no longer any support guarantee. +We currently support **Python 2.6, 2.7 and 3.3** (Python **3.2** should also +work but has a less-strong compatibility guarantee from us.) Users on Python +2.5 or older are urged to upgrade. Paramiko has two dependencies: the pure-Python ECDSA module `ecdsa`, and the PyCrypto C extension. `ecdsa` is easily installable from wherever you @@ -31,34 +31,6 @@ PyCrypto are a couple gotchas associated with installing PyCrypto: its compatibility with Python's package tools, and the fact that it is a C-based extension. -.. _pycrypto-and-pip: - -Possible gotcha on older Python and/or pip versions ---------------------------------------------------- - -We strongly recommend using ``pip`` to as it is newer and generally better than -``easy_install``. However, a combination of bugs in specific (now rather old) -versions of Python, ``pip`` and PyCrypto can prevent installation of PyCrypto. -Specifically: - -* Python = 2.5.x -* PyCrypto >= 2.1 (required for most modern versions of Paramiko) -* ``pip`` < 0.8.1 - -When all three criteria are met, you may encounter ``No such file or -directory`` IOErrors when trying to ``pip install paramiko`` or ``pip install -PyCrypto``. - -The fix is to make sure at least one of the above criteria is not met, by doing -the following (in order of preference): - -* Upgrade to ``pip`` 0.8.1 or above, e.g. by running ``pip install -U pip``. -* Upgrade to Python 2.6 or above. -* Downgrade to Paramiko 1.7.6 or 1.7.7, which do not require PyCrypto >= 2.1, - and install PyCrypto 2.0.1 (the oldest version on PyPI which works with - Paramiko 1.7.6/1.7.7) - - C extension ----------- -- cgit v1.2.3 From 4fdb4b5ae52b8e7cada05c5590a0cd0ab1b575d5 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Thu, 13 Mar 2014 21:25:44 -0700 Subject: Cut 1.10.7 --- paramiko/__init__.py | 2 +- setup.py | 2 +- sites/www/changelog.rst | 1 + 3 files changed, 3 insertions(+), 2 deletions(-) (limited to 'sites') diff --git a/paramiko/__init__.py b/paramiko/__init__.py index f081de21..b0d691c5 100644 --- a/paramiko/__init__.py +++ b/paramiko/__init__.py @@ -23,7 +23,7 @@ if sys.version_info < (2, 5): __author__ = "Jeff Forcier " -__version__ = "1.10.6" +__version__ = "1.10.7" __version_info__ = tuple([ int(d) for d in __version__.split(".") ]) __license__ = "GNU Lesser General Public License (LGPL)" diff --git a/setup.py b/setup.py index bc5f9e6d..7dc5c61e 100644 --- a/setup.py +++ b/setup.py @@ -52,7 +52,7 @@ if sys.platform == 'darwin': setup(name = "paramiko", - version = "1.10.6", + version = "1.10.7", description = "SSH2 protocol library", author = "Jeff Forcier", author_email = "jeff@bitprophet.org", diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst index fee5a962..87b05a87 100644 --- a/sites/www/changelog.rst +++ b/sites/www/changelog.rst @@ -2,6 +2,7 @@ Changelog ========= +* :release:`1.10.7 <2014-03-13>` * :support:`256 backported` Convert API documentation to Sphinx, yielding a new API docs website to replace the old Epydoc one. Thanks to Olle Lundberg for the initial conversion work. -- cgit v1.2.3 From 4e9efe48306d885281af69559a8da2194741c139 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Thu, 13 Mar 2014 21:35:48 -0700 Subject: Changelog for 1.11.5 --- sites/www/changelog.rst | 1 + 1 file changed, 1 insertion(+) (limited to 'sites') diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst index 3868f329..9e043869 100644 --- a/sites/www/changelog.rst +++ b/sites/www/changelog.rst @@ -2,6 +2,7 @@ Changelog ========= +* :release:`1.11.5 <2014-03-13>` * :release:`1.10.7 <2014-03-13>` * :support:`256 backported` Convert API documentation to Sphinx, yielding a new API docs website to replace the old Epydoc one. Thanks to Olle Lundberg for -- cgit v1.2.3 From b94af130b590692c6cdc3312d3ff768e80ab077e Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Thu, 13 Mar 2014 21:36:26 -0700 Subject: Changelog for 1.12.3 --- sites/www/changelog.rst | 1 + 1 file changed, 1 insertion(+) (limited to 'sites') diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst index a2083a83..720d93af 100644 --- a/sites/www/changelog.rst +++ b/sites/www/changelog.rst @@ -2,6 +2,7 @@ Changelog ========= +* :release:`1.12.3 <2014-03-13>` * :release:`1.11.5 <2014-03-13>` * :release:`1.10.7 <2014-03-13>` * :support:`256 backported` Convert API documentation to Sphinx, yielding a new -- cgit v1.2.3 From e032541b787e74510aa66b0a243ffc1d1a61b7f4 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Thu, 13 Mar 2014 21:37:02 -0700 Subject: Changelog for 1.13.0 --- sites/www/changelog.rst | 1 + 1 file changed, 1 insertion(+) (limited to 'sites') diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst index f0a6cf0e..8b3411a5 100644 --- a/sites/www/changelog.rst +++ b/sites/www/changelog.rst @@ -2,6 +2,7 @@ Changelog ========= +* :release:`1.13.0 <2014-03-13>` * :release:`1.12.3 <2014-03-13>` * :release:`1.11.5 <2014-03-13>` * :release:`1.10.7 <2014-03-13>` -- cgit v1.2.3 From 9ad2dec32a7cd9ba6c11969725e9512084d77e4a Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Thu, 13 Mar 2014 21:52:34 -0700 Subject: Improve string type testing in Python 2.x versions --- paramiko/file.py | 2 +- paramiko/server.py | 2 +- paramiko/sftp_client.py | 2 +- sites/www/changelog.rst | 3 +++ 4 files changed, 6 insertions(+), 3 deletions(-) (limited to 'sites') diff --git a/paramiko/file.py b/paramiko/file.py index 253ffcd0..571ee6e9 100644 --- a/paramiko/file.py +++ b/paramiko/file.py @@ -436,7 +436,7 @@ class BufferedFile (object): return if self.newlines is None: self.newlines = newline - elif (type(self.newlines) is str) and (self.newlines != newline): + elif isinstance(self.newlines, basestring) and (self.newlines != newline): self.newlines = (self.newlines, newline) elif newline not in self.newlines: self.newlines += (newline,) diff --git a/paramiko/server.py b/paramiko/server.py index c3f3a0c4..738cad1a 100644 --- a/paramiko/server.py +++ b/paramiko/server.py @@ -493,7 +493,7 @@ class InteractiveQuery (object): self.instructions = instructions self.prompts = [] for x in prompts: - if (type(x) is str) or (type(x) is unicode): + if isinstance(x, basestring): self.add_prompt(x) else: self.add_prompt(x[0], x[1]) diff --git a/paramiko/sftp_client.py b/paramiko/sftp_client.py index 0580bc43..13e830c4 100644 --- a/paramiko/sftp_client.py +++ b/paramiko/sftp_client.py @@ -660,7 +660,7 @@ class SFTPClient(BaseSFTP): msg.add_int(item) elif isinstance(item, long): msg.add_int64(item) - elif isinstance(item, str): + elif isinstance(item, basestring): msg.add_string(item) elif isinstance(item, SFTPAttributes): item._pack(msg) diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst index 9e043869..a4411c24 100644 --- a/sites/www/changelog.rst +++ b/sites/www/changelog.rst @@ -2,6 +2,9 @@ Changelog ========= +* :bug:`235` Improve string type testing in a handful of spots (e.g. ``s/if + type(x) is str/if isinstance(x, basestring)/g``.) Thanks to ``@ksamuel`` for + the report. * :release:`1.11.5 <2014-03-13>` * :release:`1.10.7 <2014-03-13>` * :support:`256 backported` Convert API documentation to Sphinx, yielding a new -- cgit v1.2.3 From 2c0544fc3504de0bb4d9c51e17abd384514030dd Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Fri, 21 Mar 2014 11:23:03 -0700 Subject: Changelog re #284 --- sites/www/changelog.rst | 2 ++ 1 file changed, 2 insertions(+) (limited to 'sites') diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst index a4411c24..cf5c142b 100644 --- a/sites/www/changelog.rst +++ b/sites/www/changelog.rst @@ -2,6 +2,8 @@ Changelog ========= +* :support:`284` Add Python language trove identifiers to ``setup.py``. Thanks + to Alex Gaynor for catch & patch. * :bug:`235` Improve string type testing in a handful of spots (e.g. ``s/if type(x) is str/if isinstance(x, basestring)/g``.) Thanks to ``@ksamuel`` for the report. -- cgit v1.2.3 From 6fac5df53598e6dedb806121ae40261d7491a341 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Fri, 21 Mar 2014 17:28:19 -0700 Subject: Start an FAQ and answer it with a new install section --- sites/www/faq.rst | 9 +++++++++ sites/www/index.rst | 1 + sites/www/installing.rst | 24 ++++++++++++++++++++++++ 3 files changed, 34 insertions(+) create mode 100644 sites/www/faq.rst (limited to 'sites') diff --git a/sites/www/faq.rst b/sites/www/faq.rst new file mode 100644 index 00000000..a7e80014 --- /dev/null +++ b/sites/www/faq.rst @@ -0,0 +1,9 @@ +=================================== +Frequently Asked/Answered Questions +=================================== + +Which version should I use? I see multiple active releases. +=========================================================== + +Please see :ref:`the installation docs ` which have an explicit +section about this topic. diff --git a/sites/www/index.rst b/sites/www/index.rst index a8e72624..0864decd 100644 --- a/sites/www/index.rst +++ b/sites/www/index.rst @@ -13,6 +13,7 @@ usage and API documentation can be found at our code documentation site, .. toctree:: changelog + faq installing contributing contact diff --git a/sites/www/installing.rst b/sites/www/installing.rst index 955a0a59..7d61632d 100644 --- a/sites/www/installing.rst +++ b/sites/www/installing.rst @@ -2,6 +2,8 @@ Installing ========== +.. _paramiko-itself: + Paramiko itself =============== @@ -23,6 +25,28 @@ PyCrypto C extension. `ecdsa` is easily installable from wherever you obtained Paramiko's package; PyCrypto may require more work. Read on for details. +.. _release-lines: + +Release lines +------------- + +Users desiring stability may wish to pin themselves to a specific release line +once they first start using Paramiko; to assist in this, we guarantee bugfixes +for at least the last 2-3 releases including the latest stable one. This currently means Paramiko **1.11** through **1.13**. + +If you're unsure which version to install, we have suggestions: + +* **Completely new users** should always default to the **latest stable + release** (as above, whatever is newest / whatever shows up with ``pip + install paramiko``.) +* **Users upgrading from a much older version** (e.g. the 1.7.x line) should + probably get the **oldest actively supported line** (see the paragraph above + this list for what that currently is.) +* **Everybody else** is hopefully already "on" a given version and can + carefully upgrade to whichever version they care to, when their release line + stops being supported. + + PyCrypto ======== -- cgit v1.2.3 From 7feeb272a059ac189de1c2c375baca0916c6fc54 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Fri, 21 Mar 2014 17:28:25 -0700 Subject: Uggh how did this slip in --- sites/www/installing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'sites') diff --git a/sites/www/installing.rst b/sites/www/installing.rst index 7d61632d..74c5c6e8 100644 --- a/sites/www/installing.rst +++ b/sites/www/installing.rst @@ -7,7 +7,7 @@ Installing Paramiko itself =============== -The recommended way to get Invoke is to **install the latest stable release** +The recommended way to get Paramiko is to **install the latest stable release** via `pip `_:: $ pip install paramiko -- cgit v1.2.3 From 4cc9d9f562235dffbd5d50fcae14e4041c4059a1 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Fri, 21 Mar 2014 17:28:25 -0700 Subject: Uggh how did this slip in --- sites/www/installing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'sites') diff --git a/sites/www/installing.rst b/sites/www/installing.rst index 0d4dc1ac..3587949f 100644 --- a/sites/www/installing.rst +++ b/sites/www/installing.rst @@ -5,7 +5,7 @@ Installing Paramiko itself =============== -The recommended way to get Invoke is to **install the latest stable release** +The recommended way to get Paramiko is to **install the latest stable release** via `pip `_:: $ pip install paramiko -- cgit v1.2.3 From a8110d8006f8ee3e520c2ee4c3ef1133b0fedf15 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Fri, 21 Mar 2014 17:32:36 -0700 Subject: Real title too large for sidebar --- sites/www/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'sites') diff --git a/sites/www/index.rst b/sites/www/index.rst index 0864decd..cb3961ce 100644 --- a/sites/www/index.rst +++ b/sites/www/index.rst @@ -13,7 +13,7 @@ usage and API documentation can be found at our code documentation site, .. toctree:: changelog - faq + FAQs installing contributing contact -- cgit v1.2.3 From 270dacaf33279bed2ae599d718183cec541e032d Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Sat, 22 Mar 2014 17:59:21 -0700 Subject: Changelog fixes #290 --- sites/www/changelog.rst | 2 ++ 1 file changed, 2 insertions(+) (limited to 'sites') diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst index cf5c142b..545afff1 100644 --- a/sites/www/changelog.rst +++ b/sites/www/changelog.rst @@ -2,6 +2,8 @@ Changelog ========= +* :support:`290` Add a ``setup.cfg`` marking Paramiko as 'universal' when + generating wheel files. Courtesy of Alex Gaynor. * :support:`284` Add Python language trove identifiers to ``setup.py``. Thanks to Alex Gaynor for catch & patch. * :bug:`235` Improve string type testing in a handful of spots (e.g. ``s/if -- cgit v1.2.3 From bd81c94825747f082c9c066abab8136d9831a3f2 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Sat, 22 Mar 2014 18:24:28 -0700 Subject: Revert "Changelog fixes #290" This reverts commit 270dacaf33279bed2ae599d718183cec541e032d. --- sites/www/changelog.rst | 2 -- 1 file changed, 2 deletions(-) (limited to 'sites') diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst index 545afff1..cf5c142b 100644 --- a/sites/www/changelog.rst +++ b/sites/www/changelog.rst @@ -2,8 +2,6 @@ Changelog ========= -* :support:`290` Add a ``setup.cfg`` marking Paramiko as 'universal' when - generating wheel files. Courtesy of Alex Gaynor. * :support:`284` Add Python language trove identifiers to ``setup.py``. Thanks to Alex Gaynor for catch & patch. * :bug:`235` Improve string type testing in a handful of spots (e.g. ``s/if -- cgit v1.2.3 From 8922bbe7d3a1d8e0dfa938068bd683580ecae880 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Sat, 22 Mar 2014 18:25:45 -0700 Subject: Revert "Revert "Changelog fixes #290"" This reverts commit bd81c94825747f082c9c066abab8136d9831a3f2. --- sites/www/changelog.rst | 2 ++ 1 file changed, 2 insertions(+) (limited to 'sites') diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst index a3558111..ade79cc5 100644 --- a/sites/www/changelog.rst +++ b/sites/www/changelog.rst @@ -2,6 +2,8 @@ Changelog ========= +* :support:`290` Add a ``setup.cfg`` marking Paramiko as 'universal' when + generating wheel files. Courtesy of Alex Gaynor. * :support:`284` Add Python language trove identifiers to ``setup.py``. Thanks to Alex Gaynor for catch & patch. * :bug:`235` Improve string type testing in a handful of spots (e.g. ``s/if -- cgit v1.2.3 From 87b57dc0cd2d8cb1b6eb605f8b885fac2937c3c6 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Sat, 22 Mar 2014 18:26:16 -0700 Subject: Expand changelog to include #292 --- sites/www/changelog.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'sites') diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst index ade79cc5..02fee80b 100644 --- a/sites/www/changelog.rst +++ b/sites/www/changelog.rst @@ -2,8 +2,9 @@ Changelog ========= -* :support:`290` Add a ``setup.cfg`` marking Paramiko as 'universal' when - generating wheel files. Courtesy of Alex Gaynor. +* :support:`290` (also :issue:`292`) Add support for building universal + (Python 2+3 compatible) wheel files during the release process. Courtesy of + Alex Gaynor. * :support:`284` Add Python language trove identifiers to ``setup.py``. Thanks to Alex Gaynor for catch & patch. * :bug:`235` Improve string type testing in a handful of spots (e.g. ``s/if -- cgit v1.2.3 From 5a430def22aa5cbd755f347c8714e4140d6cdcab Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Thu, 27 Mar 2014 14:02:03 -0700 Subject: Forgot to explicitly note python 2.5 drop in changelog for py3 --- sites/www/changelog.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'sites') diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst index 02fee80b..4563877d 100644 --- a/sites/www/changelog.rst +++ b/sites/www/changelog.rst @@ -15,7 +15,8 @@ Changelog * :release:`1.11.5 <2014-03-13>` * :release:`1.10.7 <2014-03-13>` * :feature:`16` **Python 3 support!** Our test suite passes under Python 3, and - it (& Fabric's test suite) continues to pass under Python 2. + it (& Fabric's test suite) continues to pass under Python 2. **Python 2.5 is + no longer supported with this change!** The merged code was built on many contributors' efforts, both code & feedback. In no particular order, we thank Daniel Goertzen, Ivan Kolodyazhny, -- cgit v1.2.3 From c9aa83b63e2306f75ea8f76a6235ac99ca9bbf54 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Mon, 31 Mar 2014 16:19:40 -0700 Subject: Link back to WWW in docs sidebar --- sites/docs/conf.py | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'sites') diff --git a/sites/docs/conf.py b/sites/docs/conf.py index 619ff816..f9355715 100644 --- a/sites/docs/conf.py +++ b/sites/docs/conf.py @@ -14,3 +14,8 @@ autodoc_default_flags = ['members', 'special-members'] intersphinx_mapping = { 'python': ('http://docs.python.org/2.6', None), } + +# Sister-site links to WWW +html_theme_options['extra_nav_links'] = { + "Main website": 'http://www.paramiko.org', +} -- cgit v1.2.3 From e1d92087fae4ba0404c40ef1ee383294777476b8 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Tue, 1 Apr 2014 11:13:26 -0700 Subject: Minor site cleanup --- sites/_shared_static/logo.png | Bin 6401 -> 0 bytes sites/shared_conf.py | 2 -- 2 files changed, 2 deletions(-) delete mode 100644 sites/_shared_static/logo.png (limited to 'sites') diff --git a/sites/_shared_static/logo.png b/sites/_shared_static/logo.png deleted file mode 100644 index bc76697e..00000000 Binary files a/sites/_shared_static/logo.png and /dev/null differ diff --git a/sites/shared_conf.py b/sites/shared_conf.py index 86ecdfe8..eb899834 100644 --- a/sites/shared_conf.py +++ b/sites/shared_conf.py @@ -1,6 +1,4 @@ from datetime import datetime -import os -import sys import alabaster -- cgit v1.2.3 From 80aff93d3f0040f5886e983a6ce781717f7703a4 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Tue, 1 Apr 2014 12:36:21 -0700 Subject: Fix broken tag-tree links in changelog --- sites/www/conf.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'sites') diff --git a/sites/www/conf.py b/sites/www/conf.py index 1c6c9254..0c8af16c 100644 --- a/sites/www/conf.py +++ b/sites/www/conf.py @@ -14,7 +14,8 @@ rss_description = 'Paramiko project news' # Releases changelog extension extensions.append('releases') -releases_release_uri = "https://github.com/paramiko/paramiko/tree/%s" +# Paramiko 1.x tags start with 'v'. Meh. +releases_release_uri = "https://github.com/paramiko/paramiko/tree/v%s" releases_issue_uri = "https://github.com/paramiko/paramiko/issues/%s" # Intersphinx for referencing API/usage docs -- cgit v1.2.3 From 658d202cc780f7cf536668cbca62601659369285 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Tue, 1 Apr 2014 13:28:54 -0700 Subject: This setting no longer needed & causes warnings if left in --- sites/shared_conf.py | 1 - 1 file changed, 1 deletion(-) (limited to 'sites') diff --git a/sites/shared_conf.py b/sites/shared_conf.py index eb899834..18c3bb4b 100644 --- a/sites/shared_conf.py +++ b/sites/shared_conf.py @@ -7,7 +7,6 @@ import alabaster html_theme_path = [alabaster.get_path()] extensions = ['alabaster'] # Paths relative to invoking conf.py - not this shared file -html_static_path = ['../_shared_static'] html_theme = 'alabaster' html_theme_options = { 'description': "A Python implementation of SSHv2.", -- cgit v1.2.3 From b85a09673a31719b76b3998270137f0189c226e5 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Sun, 6 Apr 2014 16:19:03 -0700 Subject: Use newer alabaster w/ showhidden in sidebar TOC Lets us not have 2x TOCs on landing page --- dev-requirements.txt | 2 +- sites/www/index.rst | 2 ++ 2 files changed, 3 insertions(+), 1 deletion(-) (limited to 'sites') diff --git a/dev-requirements.txt b/dev-requirements.txt index 5744f331..91ae8549 100644 --- a/dev-requirements.txt +++ b/dev-requirements.txt @@ -5,5 +5,5 @@ tox>=1.4,<1.5 invoke>=0.7.0 invocations>=0.5.0 sphinx>=1.1.3 -alabaster>=0.3.1 +alabaster>=0.4.0 releases>=0.5.2 diff --git a/sites/www/index.rst b/sites/www/index.rst index cb3961ce..03189cfa 100644 --- a/sites/www/index.rst +++ b/sites/www/index.rst @@ -12,6 +12,8 @@ usage and API documentation can be found at our code documentation site, `docs.paramiko.org `_. .. toctree:: + :hidden: + changelog FAQs installing -- cgit v1.2.3 From 1103416d8386e7965bae0d51d596efc4f5a75670 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Sun, 6 Apr 2014 16:24:16 -0700 Subject: Put blog into a branch --- sites/www/blog.py | 140 ----------------------------------------- sites/www/blog.rst | 16 ----- sites/www/blog/first-post.rst | 7 --- sites/www/blog/second-post.rst | 7 --- sites/www/conf.py | 6 -- sites/www/index.rst | 9 +-- 6 files changed, 2 insertions(+), 183 deletions(-) delete mode 100644 sites/www/blog.py delete mode 100644 sites/www/blog.rst delete mode 100644 sites/www/blog/first-post.rst delete mode 100644 sites/www/blog/second-post.rst (limited to 'sites') diff --git a/sites/www/blog.py b/sites/www/blog.py deleted file mode 100644 index 3b129ebf..00000000 --- a/sites/www/blog.py +++ /dev/null @@ -1,140 +0,0 @@ -from collections import namedtuple -from datetime import datetime -import time -import email.utils - -from sphinx.util.compat import Directive -from docutils import nodes - - -class BlogDateDirective(Directive): - """ - Used to parse/attach date info to blog post documents. - - No nodes generated, since none are needed. - """ - has_content = True - - def run(self): - # Tag parent document with parsed date value. - self.state.document.blog_date = datetime.strptime( - self.content[0], "%Y-%m-%d" - ) - # Don't actually insert any nodes, we're already done. - return [] - -class blog_post_list(nodes.General, nodes.Element): - pass - -class BlogPostListDirective(Directive): - """ - Simply spits out a 'blog_post_list' temporary node for replacement. - - Gets replaced at doctree-resolved time - only then will all blog post - documents be written out (& their date directives executed). - """ - def run(self): - return [blog_post_list('')] - - -Post = namedtuple('Post', 'name doc title date opener') - -def get_posts(app): - # Obtain blog posts - post_names = filter(lambda x: x.startswith('blog/'), app.env.found_docs) - posts = map(lambda x: (x, app.env.get_doctree(x)), post_names) - # Obtain common data used for list page & RSS - data = [] - for post, doc in sorted(posts, key=lambda x: x[1].blog_date, reverse=True): - # Welp. No "nice" way to get post title. Thanks Sphinx. - title = doc[0][0][0] - # Date. This may or may not end up reflecting the required - # *input* format, but doing it here gives us flexibility. - date = doc.blog_date - # 1st paragraph as opener. TODO: allow a role or something marking - # where to actually pull from? - opener = doc.traverse(nodes.paragraph)[0] - data.append(Post(post, doc, title, date, opener)) - return data - -def replace_blog_post_lists(app, doctree, fromdocname): - """ - Replace blog_post_list nodes with ordered list-o-links to posts. - """ - # Obtain blog posts - post_names = filter(lambda x: x.startswith('blog/'), app.env.found_docs) - posts = map(lambda x: (x, app.env.get_doctree(x)), post_names) - # Build "list" of links/etc - post_links = [] - for post, doc, title, date, opener in get_posts(app): - # Link itself - uri = app.builder.get_relative_uri(fromdocname, post) - link = nodes.reference('', '', refdocname=post, refuri=uri) - # Title, bolded. TODO: use 'topic' or something maybe? - link.append(nodes.strong('', title)) - date = date.strftime("%Y-%m-%d") - # Meh @ not having great docutils nodes which map to this. - html = '
%s
' % date - timestamp = nodes.raw(text=html, format='html') - # NOTE: may group these within another element later if styling - # necessitates it - group = [timestamp, nodes.paragraph('', '', link), opener] - post_links.extend(group) - - # Replace temp node(s) w/ expanded list-o-links - for node in doctree.traverse(blog_post_list): - node.replace_self(post_links) - -def rss_timestamp(timestamp): - # Use horribly inappropriate module for its magical daylight-savings-aware - # timezone madness. Props to Tinkerer for the idea. - return email.utils.formatdate( - time.mktime(timestamp.timetuple()), - localtime=True - ) - -def generate_rss(app): - # Meh at having to run this subroutine like 3x per build. Not worth trying - # to be clever for now tho. - posts_ = get_posts(app) - # LOL URLs - root = app.config.rss_link - if not root.endswith('/'): - root += '/' - # Oh boy - posts = [ - ( - root + app.builder.get_target_uri(x.name), - x.title, - str(x.opener[0]), # Grab inner text element from paragraph - rss_timestamp(x.date), - ) - for x in posts_ - ] - location = 'blog/rss.xml' - context = { - 'title': app.config.project, - 'link': root, - 'atom': root + location, - 'description': app.config.rss_description, - # 'posts' is sorted by date already - 'date': rss_timestamp(posts_[0].date), - 'posts': posts, - } - yield (location, context, 'rss.xml') - -def setup(app): - # Link in RSS feed back to main website, e.g. 'http://paramiko.org' - app.add_config_value('rss_link', None, '') - # Ditto for RSS description field - app.add_config_value('rss_description', None, '') - # Interprets date metadata in blog post documents - app.add_directive('date', BlogDateDirective) - # Inserts blog post list node (in e.g. a listing page) for replacement - # below - app.add_node(blog_post_list) - app.add_directive('blog-posts', BlogPostListDirective) - # Performs abovementioned replacement - app.connect('doctree-resolved', replace_blog_post_lists) - # Generates RSS page from whole cloth at page generation step - app.connect('html-collect-pages', generate_rss) diff --git a/sites/www/blog.rst b/sites/www/blog.rst deleted file mode 100644 index af9651e4..00000000 --- a/sites/www/blog.rst +++ /dev/null @@ -1,16 +0,0 @@ -==== -Blog -==== - -.. blog-posts directive gets replaced with an ordered list of blog posts. - -.. blog-posts:: - - -.. The following toctree ensures blog posts get processed. - -.. toctree:: - :hidden: - :glob: - - blog/* diff --git a/sites/www/blog/first-post.rst b/sites/www/blog/first-post.rst deleted file mode 100644 index 7b075073..00000000 --- a/sites/www/blog/first-post.rst +++ /dev/null @@ -1,7 +0,0 @@ -=========== -First post! -=========== - -A blog post. - -.. date:: 2013-12-04 diff --git a/sites/www/blog/second-post.rst b/sites/www/blog/second-post.rst deleted file mode 100644 index c4463f33..00000000 --- a/sites/www/blog/second-post.rst +++ /dev/null @@ -1,7 +0,0 @@ -=========== -Another one -=========== - -.. date:: 2013-12-05 - -Indeed! diff --git a/sites/www/conf.py b/sites/www/conf.py index 0c8af16c..5047fa67 100644 --- a/sites/www/conf.py +++ b/sites/www/conf.py @@ -6,12 +6,6 @@ from os.path import abspath, join, dirname sys.path.append(abspath(join(dirname(__file__), '..'))) from shared_conf import * -# Local blog extension -sys.path.append(abspath('.')) -extensions.append('blog') -rss_link = 'http://paramiko.org' -rss_description = 'Paramiko project news' - # Releases changelog extension extensions.append('releases') # Paramiko 1.x tags start with 'v'. Meh. diff --git a/sites/www/index.rst b/sites/www/index.rst index 03189cfa..77e5fcbb 100644 --- a/sites/www/index.rst +++ b/sites/www/index.rst @@ -11,6 +11,8 @@ contribution guidelines, development roadmap, news/blog, and so forth. Detailed usage and API documentation can be found at our code documentation site, `docs.paramiko.org `_. +Please see the sidebar to the left to bebin. + .. toctree:: :hidden: @@ -20,13 +22,6 @@ usage and API documentation can be found at our code documentation site, contributing contact -.. Hide blog in hidden toctree for now (to avoid warnings.) - -.. toctree:: - :hidden: - - blog - .. rubric:: Footnotes -- cgit v1.2.3 From 8b9e60f4ce66c913cd7a8371349b07e476e0e6e6 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Sun, 6 Apr 2014 16:25:02 -0700 Subject: Wow. Just wow. --- sites/www/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'sites') diff --git a/sites/www/index.rst b/sites/www/index.rst index 77e5fcbb..1b609709 100644 --- a/sites/www/index.rst +++ b/sites/www/index.rst @@ -11,7 +11,7 @@ contribution guidelines, development roadmap, news/blog, and so forth. Detailed usage and API documentation can be found at our code documentation site, `docs.paramiko.org `_. -Please see the sidebar to the left to bebin. +Please see the sidebar to the left to begin. .. toctree:: :hidden: -- cgit v1.2.3 From 57e647341f416c879ae3841c9a7be50c52a21327 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Sun, 6 Apr 2014 18:52:58 -0700 Subject: Nuke Fab-oriented link color override --- sites/shared_conf.py | 3 --- 1 file changed, 3 deletions(-) (limited to 'sites') diff --git a/sites/shared_conf.py b/sites/shared_conf.py index c61ca638..c265fc49 100644 --- a/sites/shared_conf.py +++ b/sites/shared_conf.py @@ -14,9 +14,6 @@ html_theme_options = { 'github_repo': 'paramiko', 'gittip_user': 'bitprophet', 'analytics_id': 'UA-18486793-2', - - 'link': '#3782BE', - 'link_hover': '#3782BE', } html_sidebars = { '**': [ -- cgit v1.2.3 From be7c679942b9b3a1838cce692f87e1c3d45092cf Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Mon, 14 Apr 2014 10:48:33 -0400 Subject: Errything uses intersphinx to Python --- sites/docs/conf.py | 7 +------ sites/shared_conf.py | 7 ++++++- sites/www/conf.py | 4 +--- 3 files changed, 8 insertions(+), 10 deletions(-) (limited to 'sites') diff --git a/sites/docs/conf.py b/sites/docs/conf.py index f9355715..5674fed1 100644 --- a/sites/docs/conf.py +++ b/sites/docs/conf.py @@ -5,16 +5,11 @@ sys.path.append(os.path.abspath('../..')) from shared_conf import * # Enable autodoc, intersphinx -extensions.extend(['sphinx.ext.autodoc', 'sphinx.ext.intersphinx']) +extensions.extend(['sphinx.ext.autodoc']) # Autodoc settings autodoc_default_flags = ['members', 'special-members'] -# Intersphinx connection to stdlib -intersphinx_mapping = { - 'python': ('http://docs.python.org/2.6', None), -} - # Sister-site links to WWW html_theme_options['extra_nav_links'] = { "Main website": 'http://www.paramiko.org', diff --git a/sites/shared_conf.py b/sites/shared_conf.py index c265fc49..e0afe92e 100644 --- a/sites/shared_conf.py +++ b/sites/shared_conf.py @@ -5,7 +5,7 @@ import alabaster # Alabaster theme + mini-extension html_theme_path = [alabaster.get_path()] -extensions = ['alabaster'] +extensions = ['alabaster', 'sphinx.ext.intersphinx'] # Paths relative to invoking conf.py - not this shared file html_theme = 'alabaster' html_theme_options = { @@ -24,6 +24,11 @@ html_sidebars = { ] } +# Everything intersphinx's to Python +intersphinx_mapping = { + 'python': ('http://docs.python.org/2.6', None), +} + # Regular settings project = 'Paramiko' year = datetime.now().year diff --git a/sites/www/conf.py b/sites/www/conf.py index 5047fa67..bdb5929a 100644 --- a/sites/www/conf.py +++ b/sites/www/conf.py @@ -20,9 +20,7 @@ target = join(dirname(__file__), '..', 'docs', '_build') if os.environ.get('READTHEDOCS') == 'True': # TODO: switch to docs.paramiko.org post go-live of sphinx API docs target = 'http://docs.paramiko.org/en/latest/' -intersphinx_mapping = { - 'docs': (target, None), -} +intersphinx_mapping['docs'] = (target, None) # Sister-site links to API docs html_theme_options['extra_nav_links'] = { -- cgit v1.2.3 From 160e2c08e0b7652a92d879c0e481ce72cddafef7 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Mon, 14 Apr 2014 10:48:55 -0400 Subject: Changelog, closes #295 --- sites/www/changelog.rst | 2 ++ 1 file changed, 2 insertions(+) (limited to 'sites') diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst index 4563877d..eff8c2e8 100644 --- a/sites/www/changelog.rst +++ b/sites/www/changelog.rst @@ -2,6 +2,8 @@ Changelog ========= +* :support:`295` Swap out a bunch of PyCrypto hash functions with use of + `hashlib` * :support:`290` (also :issue:`292`) Add support for building universal (Python 2+3 compatible) wheel files during the release process. Courtesy of Alex Gaynor. -- cgit v1.2.3 From 1e0e296b05a3e63b33291cfe3d688a435f592c3c Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Mon, 14 Apr 2014 10:50:12 -0400 Subject: Derp --- sites/www/changelog.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'sites') diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst index eff8c2e8..5f019bb8 100644 --- a/sites/www/changelog.rst +++ b/sites/www/changelog.rst @@ -3,7 +3,7 @@ Changelog ========= * :support:`295` Swap out a bunch of PyCrypto hash functions with use of - `hashlib` + `hashlib`. Thanks to Alex Gaynor. * :support:`290` (also :issue:`292`) Add support for building universal (Python 2+3 compatible) wheel files during the release process. Courtesy of Alex Gaynor. -- cgit v1.2.3 From 9e2e9812247adbedf0eab84ad5cdd80c458d68f9 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Mon, 14 Apr 2014 11:05:25 -0400 Subject: Changelog, closes #297 --- sites/www/changelog.rst | 2 ++ 1 file changed, 2 insertions(+) (limited to 'sites') diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst index 5f019bb8..653502ca 100644 --- a/sites/www/changelog.rst +++ b/sites/www/changelog.rst @@ -2,6 +2,8 @@ Changelog ========= +* :support:`297` Replace PyCrypto's ``Random`` with `os.urandom` for improved + speed and security. Thanks again to Alex. * :support:`295` Swap out a bunch of PyCrypto hash functions with use of `hashlib`. Thanks to Alex Gaynor. * :support:`290` (also :issue:`292`) Add support for building universal -- cgit v1.2.3 From e96e2653a2ca0a465d2773b1fe468c0f87e758bc Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Mon, 14 Apr 2014 11:29:41 -0400 Subject: Changelog, closes #299 --- sites/www/changelog.rst | 2 ++ 1 file changed, 2 insertions(+) (limited to 'sites') diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst index 653502ca..2c4c1cf7 100644 --- a/sites/www/changelog.rst +++ b/sites/www/changelog.rst @@ -2,6 +2,8 @@ Changelog ========= +* :support:`299` Use deterministic signatures for ECDSA keys for improved + security. Thanks to Alex Gaynor. * :support:`297` Replace PyCrypto's ``Random`` with `os.urandom` for improved speed and security. Thanks again to Alex. * :support:`295` Swap out a bunch of PyCrypto hash functions with use of -- cgit v1.2.3 From d02ae566014c6d79f61f7538c979d6560c1de629 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Mon, 14 Apr 2014 18:28:03 -0400 Subject: Note changelog location in contribution docs --- sites/www/contributing.rst | 3 +++ 1 file changed, 3 insertions(+) (limited to 'sites') diff --git a/sites/www/contributing.rst b/sites/www/contributing.rst index 2b752cc5..634c2b26 100644 --- a/sites/www/contributing.rst +++ b/sites/www/contributing.rst @@ -17,3 +17,6 @@ How to submit bug reports or new code Please see `this project-agnostic contribution guide `_ - we follow it explicitly. + +Our current changelog is located in ``sites/www/changelog.rst`` - the top +level files like ``ChangeLog.*`` and ``NEWS`` are historical only. -- cgit v1.2.3 From 34d03ae3dc4f08657f638e85c4184fb3b1a64e64 Mon Sep 17 00:00:00 2001 From: Chris Rose Date: Mon, 14 Apr 2014 17:38:05 -0400 Subject: Revert a regression in DSS key generation A change in f0017b833098 caused a random regression in DSS key signing due to moving the padding on the integers generated by DSA from the left to the right. So, for example, if signing the test case string "jerri blank", the random number might be generated as: k=703745698612177278239572677252380378525350342103 If so, the signature parts will be: r=184615963997659989901526712385095827509599268253 s=2682547683721156713440053885014828604195555319 Note the s being shorter. Prior to f0017b833098, s would be right-padded with zeros: s=268254768372115671344005388501482860419555531900 After, it would be left-padded: s=002682547683721156713440053885014828604195555319 When converting back to a long, that loses the padding. This change restores the behaviour. Fixes #308 --- paramiko/dsskey.py | 4 ++-- sites/www/changelog.rst | 2 ++ 2 files changed, 4 insertions(+), 2 deletions(-) (limited to 'sites') diff --git a/paramiko/dsskey.py b/paramiko/dsskey.py index c26966e8..6a46d326 100644 --- a/paramiko/dsskey.py +++ b/paramiko/dsskey.py @@ -111,9 +111,9 @@ class DSSKey (PKey): rstr = util.deflate_long(r, 0) sstr = util.deflate_long(s, 0) if len(rstr) < 20: - rstr += zero_byte * (20 - len(rstr)) + rstr = zero_byte * (20 - len(rstr)) + rstr if len(sstr) < 20: - sstr += zero_byte * (20 - len(sstr)) + sstr = zero_byte * (20 - len(sstr)) + sstr m.add_string(rstr + sstr) return m diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst index 02fee80b..6737fdc0 100644 --- a/sites/www/changelog.rst +++ b/sites/www/changelog.rst @@ -2,6 +2,8 @@ Changelog ========= +* :bug:`308` Fix regression in dsskey.py that caused sporadic signature + verification failures. Thanks to Chris Rose. * :support:`290` (also :issue:`292`) Add support for building universal (Python 2+3 compatible) wheel files during the release process. Courtesy of Alex Gaynor. -- cgit v1.2.3 From c14de1d93516c9aec18749cb501febf0b2cee530 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Tue, 15 Apr 2014 15:04:46 -0400 Subject: Show Travis status in website sidebar --- sites/shared_conf.py | 1 + 1 file changed, 1 insertion(+) (limited to 'sites') diff --git a/sites/shared_conf.py b/sites/shared_conf.py index e0afe92e..69908388 100644 --- a/sites/shared_conf.py +++ b/sites/shared_conf.py @@ -14,6 +14,7 @@ html_theme_options = { 'github_repo': 'paramiko', 'gittip_user': 'bitprophet', 'analytics_id': 'UA-18486793-2', + 'travis_button': True, } html_sidebars = { '**': [ -- cgit v1.2.3 From 6e9abc39cfff94e0dc36ebe6b939caa8d2eafee0 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Wed, 16 Apr 2014 15:07:56 -0400 Subject: Fix logging error in sftp_client for filenames containing the character. Bug reported here: http://vlists.pepperfish.net/pipermail/obnam-flarn.net/2013-May/000767.html Antoine Brenner Backported to 1.11 by @bitprophet Conflicts: paramiko/sftp_client.py sites/www/changelog.rst tests/test_sftp.py --- paramiko/sftp_client.py | 6 ++++-- sites/www/changelog.rst | 2 ++ tests/test_sftp.py | 23 +++++++++++++++++++++++ 3 files changed, 29 insertions(+), 2 deletions(-) (limited to 'sites') diff --git a/paramiko/sftp_client.py b/paramiko/sftp_client.py index 13e830c4..907ec413 100644 --- a/paramiko/sftp_client.py +++ b/paramiko/sftp_client.py @@ -105,9 +105,11 @@ class SFTPClient(BaseSFTP): def _log(self, level, msg, *args): if isinstance(msg, list): for m in msg: - super(SFTPClient, self)._log(level, "[chan %s] " + m, *([ self.sock.get_name() ] + list(args))) + self._log(level, m, *args) else: - super(SFTPClient, self)._log(level, "[chan %s] " + msg, *([ self.sock.get_name() ] + list(args))) + # escape '%' in msg (they could come from file or directory names) before logging + msg = msg.replace('%','%%') + super(SFTPClient, self)._log(level, "[chan %s] " + msg, *([self.sock.get_name()] + list(args))) def close(self): """ diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst index cf5c142b..a7d9f93d 100644 --- a/sites/www/changelog.rst +++ b/sites/www/changelog.rst @@ -2,6 +2,8 @@ Changelog ========= +* :bug:`-` Fix logging error in sftp_client for filenames containing the '%' + character. Thanks to Antoine Brenner. * :support:`284` Add Python language trove identifiers to ``setup.py``. Thanks to Alex Gaynor for catch & patch. * :bug:`235` Improve string type testing in a handful of spots (e.g. ``s/if diff --git a/tests/test_sftp.py b/tests/test_sftp.py index cc512c18..a136f823 100755 --- a/tests/test_sftp.py +++ b/tests/test_sftp.py @@ -36,6 +36,7 @@ import StringIO import paramiko from stub_sftp import StubServer, StubSFTPServer from loop import LoopSocket +import paramiko.util from paramiko.sftp_attr import SFTPAttributes ARTICLE = ''' @@ -738,3 +739,25 @@ class SFTPTest (unittest.TestCase): self.assertNotEqual(attrs, None) finally: sftp.remove(target) + + + def test_N_file_with_percent(self): + """ + verify that we can create a file with a '%' in the filename. + ( it needs to be properly escaped by _log() ) + """ + self.assertTrue( paramiko.util.get_logger("paramiko").handlers, "This unit test requires logging to be enabled" ) + f = sftp.open(FOLDER + '/test%file', 'w') + try: + self.assertEqual(f.stat().st_size, 0) + finally: + f.close() + sftp.remove(FOLDER + '/test%file') + + +if __name__ == '__main__': + SFTPTest.init_loopback() + # logging is required by test_N_file_with_percent + paramiko.util.log_to_file('test_sftp.log') + from unittest import main + main() -- cgit v1.2.3 From 30f6f98afd718daf7517b24cd9e85c218f482552 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Wed, 16 Apr 2014 15:51:01 -0400 Subject: Added self.args for exception classes. Used for unpickling Related to fabric/fabric#986 and fabric/fabric#714 Conflicts: sites/www/changelog.rst --- paramiko/ssh_exception.py | 12 +++++++++++- sites/www/changelog.rst | 4 ++++ 2 files changed, 15 insertions(+), 1 deletion(-) (limited to 'sites') diff --git a/paramiko/ssh_exception.py b/paramiko/ssh_exception.py index 63ca6409..b99e42b3 100644 --- a/paramiko/ssh_exception.py +++ b/paramiko/ssh_exception.py @@ -59,7 +59,9 @@ class BadAuthenticationType (AuthenticationException): def __init__(self, explanation, types): AuthenticationException.__init__(self, explanation) self.allowed_types = types - + # for unpickling + self.args = (explanation, types, ) + def __str__(self): return SSHException.__str__(self) + ' (allowed_types=%r)' % self.allowed_types @@ -73,6 +75,8 @@ class PartialAuthentication (AuthenticationException): def __init__(self, types): AuthenticationException.__init__(self, 'partial authentication') self.allowed_types = types + # for unpickling + self.args = (types, ) class ChannelException (SSHException): @@ -86,6 +90,8 @@ class ChannelException (SSHException): def __init__(self, code, text): SSHException.__init__(self, text) self.code = code + # for unpickling + self.args = (code, text, ) class BadHostKeyException (SSHException): @@ -103,6 +109,8 @@ class BadHostKeyException (SSHException): self.hostname = hostname self.key = got_key self.expected_key = expected_key + # for unpickling + self.args = (hostname, got_key, expected_key, ) class ProxyCommandFailure (SSHException): @@ -119,3 +127,5 @@ class ProxyCommandFailure (SSHException): ) ) self.error = error + # for unpickling + self.args = (command, error, ) diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst index a7d9f93d..b84f7758 100644 --- a/sites/www/changelog.rst +++ b/sites/www/changelog.rst @@ -2,6 +2,10 @@ Changelog ========= +* :bug:`-` Added self.args for exception classes. Used for unpickling. Related + to (`Fabric #986 `_, `Fabric + #714 `_). Thanks to Alex + Plugaru. * :bug:`-` Fix logging error in sftp_client for filenames containing the '%' character. Thanks to Antoine Brenner. * :support:`284` Add Python language trove identifiers to ``setup.py``. Thanks -- cgit v1.2.3 From 3fce8abf68f386d18f2fad9f086e0d436af57b3a Mon Sep 17 00:00:00 2001 From: Antoine Brenner Date: Wed, 16 Apr 2014 21:58:03 +0200 Subject: BufferedFile.read() now returns byte strings instead of text strings It is the right thing to do since we have no idea what encoding the file is in, or even if the file is text data. BufferedFile.readline() is unchanged and returns text strings assuming the file is utf-8 encoded. This should fix the following issue: http://comments.gmane.org/gmane.comp.sysutils.backup.obnam/252 Antoine Brenner Conflicts: sites/www/changelog.rst --- paramiko/file.py | 21 +++++++++++++++------ sites/www/changelog.rst | 7 +++++++ tests/test_file.py | 45 +++++++++++++++++++++++++-------------------- tests/test_sftp.py | 10 +++++----- tests/test_sftp_big.py | 4 ++-- 5 files changed, 54 insertions(+), 33 deletions(-) (limited to 'sites') diff --git a/paramiko/file.py b/paramiko/file.py index f57aa79f..725ca5f6 100644 --- a/paramiko/file.py +++ b/paramiko/file.py @@ -124,10 +124,15 @@ class BufferedFile (object): file first). If the ``size`` argument is negative or omitted, read all the remaining data in the file. + `'b' mode flag is ignored (self.FLAG_BINARY in self._flags), because + SSH treats all files as binary, since we have no idea what encoding + the file is in, or even if the file is text data. + + :param int size: maximum number of bytes to read :return: - data read from the file (as a `str`), or an empty string if EOF was - encountered immediately + data read from the file (as bytes ), or an empty string + if EOF was encountered immediately """ if self._closed: raise IOError('File is closed') @@ -148,12 +153,12 @@ class BufferedFile (object): result += new_data self._realpos += len(new_data) self._pos += len(new_data) - return result if self._flags & self.FLAG_BINARY else u(result) + return result if size <= len(self._rbuffer): result = self._rbuffer[:size] self._rbuffer = self._rbuffer[size:] self._pos += len(result) - return result if self._flags & self.FLAG_BINARY else u(result) + return result while len(self._rbuffer) < size: read_size = size - len(self._rbuffer) if self._flags & self.FLAG_BUFFERED: @@ -169,7 +174,7 @@ class BufferedFile (object): result = self._rbuffer[:size] self._rbuffer = self._rbuffer[size:] self._pos += len(result) - return result if self._flags & self.FLAG_BINARY else u(result) + return result def readline(self, size=None): """ @@ -186,8 +191,12 @@ class BufferedFile (object): :param int size: maximum length of returned string. :return: - next line of the file (`str`), or an empty string if the end of the + next line of the file, or an empty string if the end of the file has been reached. + If the file was opened in binary 'b' mode: bytes are returned + Else: the encoding of the file is assumed to be utf-8 (default + encoding used by paramiko.py3compat.u) and character strings + (`str`) are returned """ # it's almost silly how complex this function is. if self._closed: diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst index 21ba6e12..67c4f827 100644 --- a/sites/www/changelog.rst +++ b/sites/www/changelog.rst @@ -2,6 +2,13 @@ Changelog ========= +* :bug: BufferedFile.read() now returns byte strings instead of text strings + It is the right thing to do since we have no idea what encoding the file + is in, or even if the file is text data. BufferedFile.readline() is + unchanged and returns text strings assuming the file is utf-8 encoded. + This should fix the following issue: + http://comments.gmane.org/gmane.comp.sysutils.backup.obnam/252 + Thanks Antoine Brenner * :bug:`-` Added self.args for exception classes. Used for unpickling. Related to (`Fabric #986 `_, `Fabric #714 `_). Thanks to Alex diff --git a/tests/test_file.py b/tests/test_file.py index e11d7fd5..c6edd7af 100755 --- a/tests/test_file.py +++ b/tests/test_file.py @@ -53,7 +53,7 @@ class BufferedFileTest (unittest.TestCase): def test_1_simple(self): f = LoopbackFile('r') try: - f.write('hi') + f.write(b'hi') self.assertTrue(False, 'no exception on write to read-only file') except: pass @@ -69,7 +69,7 @@ class BufferedFileTest (unittest.TestCase): def test_2_readline(self): f = LoopbackFile('r+U') - f.write('First line.\nSecond line.\r\nThird line.\nFinal line non-terminated.') + f.write(b'First line.\nSecond line.\r\nThird line.\nFinal line non-terminated.') self.assertEqual(f.readline(), 'First line.\n') # universal newline mode should convert this linefeed: self.assertEqual(f.readline(), 'Second line.\n') @@ -93,9 +93,9 @@ class BufferedFileTest (unittest.TestCase): try to trick the linefeed detector. """ f = LoopbackFile('r+U') - f.write('First line.\r') + f.write(b'First line.\r') self.assertEqual(f.readline(), 'First line.\n') - f.write('\nSecond.\r\n') + f.write(b'\nSecond.\r\n') self.assertEqual(f.readline(), 'Second.\n') f.close() self.assertEqual(f.newlines, crlf) @@ -105,7 +105,7 @@ class BufferedFileTest (unittest.TestCase): verify that write buffering is on. """ f = LoopbackFile('r+', 1) - f.write('Complete line.\nIncomplete line.') + f.write(b'Complete line.\nIncomplete line.') self.assertEqual(f.readline(), 'Complete line.\n') self.assertEqual(f.readline(), '') f.write('..\n') @@ -118,12 +118,12 @@ class BufferedFileTest (unittest.TestCase): """ f = LoopbackFile('r+', 512) f.write('Not\nquite\n512 bytes.\n') - self.assertEqual(f.read(1), '') + self.assertEqual(f.read(1), b'') f.flush() - self.assertEqual(f.read(5), 'Not\nq') - self.assertEqual(f.read(10), 'uite\n512 b') - self.assertEqual(f.read(9), 'ytes.\n') - self.assertEqual(f.read(3), '') + self.assertEqual(f.read(5), b'Not\nq') + self.assertEqual(f.read(10), b'uite\n512 b') + self.assertEqual(f.read(9), b'ytes.\n') + self.assertEqual(f.read(3), b'') f.close() def test_6_buffering(self): @@ -131,12 +131,12 @@ class BufferedFileTest (unittest.TestCase): verify that flushing happens automatically on buffer crossing. """ f = LoopbackFile('r+', 16) - f.write('Too small.') - self.assertEqual(f.read(4), '') - f.write(' ') - self.assertEqual(f.read(4), '') - f.write('Enough.') - self.assertEqual(f.read(20), 'Too small. Enough.') + f.write(b'Too small.') + self.assertEqual(f.read(4), b'') + f.write(b' ') + self.assertEqual(f.read(4), b'') + f.write(b'Enough.') + self.assertEqual(f.read(20), b'Too small. Enough.') f.close() def test_7_read_all(self): @@ -144,9 +144,14 @@ class BufferedFileTest (unittest.TestCase): verify that read(-1) returns everything left in the file. """ f = LoopbackFile('r+', 16) - f.write('The first thing you need to do is open your eyes. ') - f.write('Then, you need to close them again.\n') + f.write(b'The first thing you need to do is open your eyes. ') + f.write(b'Then, you need to close them again.\n') s = f.read(-1) - self.assertEqual(s, 'The first thing you need to do is open your eyes. Then, you ' + - 'need to close them again.\n') + self.assertEqual(s, b'The first thing you need to do is open your eyes. Then, you ' + + b'need to close them again.\n') f.close() + +if __name__ == '__main__': + from unittest import main + main() + diff --git a/tests/test_sftp.py b/tests/test_sftp.py index e0534eb0..720b8215 100755 --- a/tests/test_sftp.py +++ b/tests/test_sftp.py @@ -405,7 +405,7 @@ class SFTPTest (unittest.TestCase): self.assertEqual(sftp.stat(FOLDER + '/testing.txt').st_size, 13) with sftp.open(FOLDER + '/testing.txt', 'r') as f: data = f.read(20) - self.assertEqual(data, 'hello kiddy.\n') + self.assertEqual(data, b'hello kiddy.\n') finally: sftp.remove(FOLDER + '/testing.txt') @@ -466,8 +466,8 @@ class SFTPTest (unittest.TestCase): f.write('?\n') with sftp.open(FOLDER + '/happy.txt', 'r') as f: - self.assertEqual(f.readline(), 'full line?\n') - self.assertEqual(f.read(7), 'partial') + self.assertEqual(f.readline(), u'full line?\n') + self.assertEqual(f.read(7), b'partial') finally: try: sftp.remove(FOLDER + '/happy.txt') @@ -662,8 +662,8 @@ class SFTPTest (unittest.TestCase): fd, localname = mkstemp() os.close(fd) - text = 'All I wanted was a plastic bunny rabbit.\n' - with open(localname, 'w') as f: + text = b'All I wanted was a plastic bunny rabbit.\n' + with open(localname, 'wb') as f: f.write(text) saved_progress = [] diff --git a/tests/test_sftp_big.py b/tests/test_sftp_big.py index 521fbdc8..abed27b8 100644 --- a/tests/test_sftp_big.py +++ b/tests/test_sftp_big.py @@ -85,7 +85,7 @@ class BigSFTPTest (unittest.TestCase): write a 1MB file with no buffering. """ sftp = get_sftp() - kblob = (1024 * 'x') + kblob = (1024 * b'x') start = time.time() try: with sftp.open('%s/hongry.txt' % FOLDER, 'w') as f: @@ -231,7 +231,7 @@ class BigSFTPTest (unittest.TestCase): without using it, to verify that paramiko doesn't get confused. """ sftp = get_sftp() - kblob = (1024 * 'x') + kblob = (1024 * b'x') try: with sftp.open('%s/hongry.txt' % FOLDER, 'w') as f: f.set_pipelined(True) -- cgit v1.2.3 From 5636381591aa26a9f31efab450b6bfdd6659cbb3 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Thu, 24 Apr 2014 09:33:38 -0700 Subject: Reword docs/changelog re #315 --- paramiko/file.py | 19 +++++++++---------- sites/www/changelog.rst | 20 +++++++++++++------- 2 files changed, 22 insertions(+), 17 deletions(-) (limited to 'sites') diff --git a/paramiko/file.py b/paramiko/file.py index 725ca5f6..70243e40 100644 --- a/paramiko/file.py +++ b/paramiko/file.py @@ -124,15 +124,14 @@ class BufferedFile (object): file first). If the ``size`` argument is negative or omitted, read all the remaining data in the file. - `'b' mode flag is ignored (self.FLAG_BINARY in self._flags), because - SSH treats all files as binary, since we have no idea what encoding - the file is in, or even if the file is text data. - + ``'b'`` mode flag is ignored (``self.FLAG_BINARY`` in ``self._flags``), + because SSH treats all files as binary, since we have no idea what + encoding the file is in, or even if the file is text data. :param int size: maximum number of bytes to read :return: - data read from the file (as bytes ), or an empty string - if EOF was encountered immediately + data read from the file (as bytes), or an empty string if EOF was + encountered immediately """ if self._closed: raise IOError('File is closed') @@ -193,10 +192,10 @@ class BufferedFile (object): :return: next line of the file, or an empty string if the end of the file has been reached. - If the file was opened in binary 'b' mode: bytes are returned - Else: the encoding of the file is assumed to be utf-8 (default - encoding used by paramiko.py3compat.u) and character strings - (`str`) are returned + + If the file was opened in binary (``'b'``) mode: bytes are returned + Else: the encoding of the file is assumed to be UTF-8 and character + strings (`str`) are returned """ # it's almost silly how complex this function is. if self._closed: diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst index 67c4f827..8a4b0f56 100644 --- a/sites/www/changelog.rst +++ b/sites/www/changelog.rst @@ -2,13 +2,19 @@ Changelog ========= -* :bug: BufferedFile.read() now returns byte strings instead of text strings - It is the right thing to do since we have no idea what encoding the file - is in, or even if the file is text data. BufferedFile.readline() is - unchanged and returns text strings assuming the file is utf-8 encoded. - This should fix the following issue: - http://comments.gmane.org/gmane.comp.sysutils.backup.obnam/252 - Thanks Antoine Brenner +* :bug:`-` `paramiko.file.BufferedFile.read` incorrectly returned text strings + after the Python 3 migration, despite bytes being more appropriate for file + contents (which may be binary or of an unknown encoding.) This has been + addressed. + + .. note:: + `paramiko.file.BufferedFile.readline` continues to return strings, not + bytes, as "lines" only make sense for textual data. It assumes UTF-8 by + default. + + This should fix `this issue raised on the Obnam mailing list + `_. Thanks + to Antoine Brenner for the patch. * :bug:`-` Added self.args for exception classes. Used for unpickling. Related to (`Fabric #986 `_, `Fabric #714 `_). Thanks to Alex -- cgit v1.2.3 From a759a8e8df0127e624d69f0e2c02704a95e0cc0c Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Thu, 24 Apr 2014 09:33:48 -0700 Subject: Fix incorrect monospacing --- sites/www/installing.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'sites') diff --git a/sites/www/installing.rst b/sites/www/installing.rst index 3587949f..0ca9b156 100644 --- a/sites/www/installing.rst +++ b/sites/www/installing.rst @@ -18,8 +18,8 @@ We currently support **Python 2.5/2.6/2.7**, with support for Python 3 coming soon. Users on Python 2.4 or older are urged to upgrade. Paramiko *may* work on Python 2.4 still, but there is no longer any support guarantee. -Paramiko has two dependencies: the pure-Python ECDSA module `ecdsa`, and the -PyCrypto C extension. `ecdsa` is easily installable from wherever you +Paramiko has two dependencies: the pure-Python ECDSA module ``ecdsa``, and the +PyCrypto C extension. ``ecdsa`` is easily installable from wherever you obtained Paramiko's package; PyCrypto may require more work. Read on for details. -- cgit v1.2.3 From ac4c75471821fa5686c1f15e1b8613fe70639355 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Thu, 24 Apr 2014 09:33:48 -0700 Subject: Fix incorrect monospacing --- sites/www/installing.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'sites') diff --git a/sites/www/installing.rst b/sites/www/installing.rst index 3587949f..0ca9b156 100644 --- a/sites/www/installing.rst +++ b/sites/www/installing.rst @@ -18,8 +18,8 @@ We currently support **Python 2.5/2.6/2.7**, with support for Python 3 coming soon. Users on Python 2.4 or older are urged to upgrade. Paramiko *may* work on Python 2.4 still, but there is no longer any support guarantee. -Paramiko has two dependencies: the pure-Python ECDSA module `ecdsa`, and the -PyCrypto C extension. `ecdsa` is easily installable from wherever you +Paramiko has two dependencies: the pure-Python ECDSA module ``ecdsa``, and the +PyCrypto C extension. ``ecdsa`` is easily installable from wherever you obtained Paramiko's package; PyCrypto may require more work. Read on for details. -- cgit v1.2.3 From 4fe3ad2220996354b7f096cbd2d3000caf5cfdf0 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Sun, 6 Apr 2014 18:52:58 -0700 Subject: Nuke Fab-oriented link color override --- sites/shared_conf.py | 3 --- 1 file changed, 3 deletions(-) (limited to 'sites') diff --git a/sites/shared_conf.py b/sites/shared_conf.py index c61ca638..c265fc49 100644 --- a/sites/shared_conf.py +++ b/sites/shared_conf.py @@ -14,9 +14,6 @@ html_theme_options = { 'github_repo': 'paramiko', 'gittip_user': 'bitprophet', 'analytics_id': 'UA-18486793-2', - - 'link': '#3782BE', - 'link_hover': '#3782BE', } html_sidebars = { '**': [ -- cgit v1.2.3 From a1c2a9829a620c3ace6ddc6187bf05262e10b137 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Mon, 14 Apr 2014 10:48:33 -0400 Subject: Errything uses intersphinx to Python --- sites/docs/conf.py | 7 +------ sites/shared_conf.py | 7 ++++++- sites/www/conf.py | 4 +--- 3 files changed, 8 insertions(+), 10 deletions(-) (limited to 'sites') diff --git a/sites/docs/conf.py b/sites/docs/conf.py index f9355715..5674fed1 100644 --- a/sites/docs/conf.py +++ b/sites/docs/conf.py @@ -5,16 +5,11 @@ sys.path.append(os.path.abspath('../..')) from shared_conf import * # Enable autodoc, intersphinx -extensions.extend(['sphinx.ext.autodoc', 'sphinx.ext.intersphinx']) +extensions.extend(['sphinx.ext.autodoc']) # Autodoc settings autodoc_default_flags = ['members', 'special-members'] -# Intersphinx connection to stdlib -intersphinx_mapping = { - 'python': ('http://docs.python.org/2.6', None), -} - # Sister-site links to WWW html_theme_options['extra_nav_links'] = { "Main website": 'http://www.paramiko.org', diff --git a/sites/shared_conf.py b/sites/shared_conf.py index c265fc49..e0afe92e 100644 --- a/sites/shared_conf.py +++ b/sites/shared_conf.py @@ -5,7 +5,7 @@ import alabaster # Alabaster theme + mini-extension html_theme_path = [alabaster.get_path()] -extensions = ['alabaster'] +extensions = ['alabaster', 'sphinx.ext.intersphinx'] # Paths relative to invoking conf.py - not this shared file html_theme = 'alabaster' html_theme_options = { @@ -24,6 +24,11 @@ html_sidebars = { ] } +# Everything intersphinx's to Python +intersphinx_mapping = { + 'python': ('http://docs.python.org/2.6', None), +} + # Regular settings project = 'Paramiko' year = datetime.now().year diff --git a/sites/www/conf.py b/sites/www/conf.py index 1c6c9254..c7828203 100644 --- a/sites/www/conf.py +++ b/sites/www/conf.py @@ -25,9 +25,7 @@ target = join(dirname(__file__), '..', 'docs', '_build') if os.environ.get('READTHEDOCS') == 'True': # TODO: switch to docs.paramiko.org post go-live of sphinx API docs target = 'http://docs.paramiko.org/en/latest/' -intersphinx_mapping = { - 'docs': (target, None), -} +intersphinx_mapping['docs'] = (target, None) # Sister-site links to API docs html_theme_options['extra_nav_links'] = { -- cgit v1.2.3 From 24309559bbdc4742a94854eb33c9d6047635497c Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Tue, 15 Apr 2014 15:04:46 -0400 Subject: Show Travis status in website sidebar --- sites/shared_conf.py | 1 + 1 file changed, 1 insertion(+) (limited to 'sites') diff --git a/sites/shared_conf.py b/sites/shared_conf.py index e0afe92e..69908388 100644 --- a/sites/shared_conf.py +++ b/sites/shared_conf.py @@ -14,6 +14,7 @@ html_theme_options = { 'github_repo': 'paramiko', 'gittip_user': 'bitprophet', 'analytics_id': 'UA-18486793-2', + 'travis_button': True, } html_sidebars = { '**': [ -- cgit v1.2.3 From 74c612e328b962f348f9f425f47d1ecbaef3b207 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Sun, 6 Apr 2014 16:19:03 -0700 Subject: Use newer alabaster w/ showhidden in sidebar TOC Lets us not have 2x TOCs on landing page --- dev-requirements.txt | 2 +- sites/www/index.rst | 2 ++ 2 files changed, 3 insertions(+), 1 deletion(-) (limited to 'sites') diff --git a/dev-requirements.txt b/dev-requirements.txt index 5744f331..91ae8549 100644 --- a/dev-requirements.txt +++ b/dev-requirements.txt @@ -5,5 +5,5 @@ tox>=1.4,<1.5 invoke>=0.7.0 invocations>=0.5.0 sphinx>=1.1.3 -alabaster>=0.3.1 +alabaster>=0.4.0 releases>=0.5.2 diff --git a/sites/www/index.rst b/sites/www/index.rst index 7fefedd2..0f07d7e9 100644 --- a/sites/www/index.rst +++ b/sites/www/index.rst @@ -12,6 +12,8 @@ usage and API documentation can be found at our code documentation site, `docs.paramiko.org `_. .. toctree:: + :hidden: + changelog installing contributing -- cgit v1.2.3 From c0667e1e6a1dd9b6cf2e47762b51d085417eb7c8 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Wed, 7 May 2014 13:39:39 -0700 Subject: Cut 1.11.6 --- paramiko/__init__.py | 2 +- setup.py | 2 +- sites/www/changelog.rst | 1 + 3 files changed, 3 insertions(+), 2 deletions(-) (limited to 'sites') diff --git a/paramiko/__init__.py b/paramiko/__init__.py index ce3f0cf9..25ec6679 100644 --- a/paramiko/__init__.py +++ b/paramiko/__init__.py @@ -23,7 +23,7 @@ if sys.version_info < (2, 5): __author__ = "Jeff Forcier " -__version__ = "1.11.5" +__version__ = "1.11.6" __version_info__ = tuple([ int(d) for d in __version__.split(".") ]) __license__ = "GNU Lesser General Public License (LGPL)" diff --git a/setup.py b/setup.py index 6222a7b0..6cb40de1 100644 --- a/setup.py +++ b/setup.py @@ -53,7 +53,7 @@ if sys.platform == 'darwin': setup( name = "paramiko", - version = "1.11.5", + version = "1.11.6", description = "SSH2 protocol library", long_description = longdesc, author = "Jeff Forcier", diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst index b84f7758..6ad85927 100644 --- a/sites/www/changelog.rst +++ b/sites/www/changelog.rst @@ -2,6 +2,7 @@ Changelog ========= +* :release:`1.11.6 <2014-05-07>` * :bug:`-` Added self.args for exception classes. Used for unpickling. Related to (`Fabric #986 `_, `Fabric #714 `_). Thanks to Alex -- cgit v1.2.3 From 09e9d48db06b7e6eff090dc2cbbb94fef18a1b2c Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Wed, 7 May 2014 13:47:09 -0700 Subject: Cut 1.12.4 --- paramiko/__init__.py | 2 +- setup.py | 2 +- sites/www/changelog.rst | 1 + 3 files changed, 3 insertions(+), 2 deletions(-) (limited to 'sites') diff --git a/paramiko/__init__.py b/paramiko/__init__.py index 63d52bd3..d6a03898 100644 --- a/paramiko/__init__.py +++ b/paramiko/__init__.py @@ -23,7 +23,7 @@ if sys.version_info < (2, 5): __author__ = "Jeff Forcier " -__version__ = "1.12.3" +__version__ = "1.12.4" __version_info__ = tuple([ int(d) for d in __version__.split(".") ]) __license__ = "GNU Lesser General Public License (LGPL)" diff --git a/setup.py b/setup.py index 5fd9d044..04286b15 100644 --- a/setup.py +++ b/setup.py @@ -55,7 +55,7 @@ if sys.platform == 'darwin': setup( name = "paramiko", - version = "1.12.3", + version = "1.12.4", description = "SSH2 protocol library", long_description = longdesc, author = "Jeff Forcier", diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst index 3f8fbdc7..524cf0dc 100644 --- a/sites/www/changelog.rst +++ b/sites/www/changelog.rst @@ -2,6 +2,7 @@ Changelog ========= +* :release:`1.12.4 <2014-05-07>` * :release:`1.11.6 <2014-05-07>` * :bug:`-` Added self.args for exception classes. Used for unpickling. Related to (`Fabric #986 `_, `Fabric -- cgit v1.2.3 From 7484a221803a3f9aa959d9fd02770ee9c2c90ad5 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Wed, 7 May 2014 14:14:05 -0700 Subject: Cut 1.13.1 --- paramiko/__init__.py | 2 +- setup.py | 2 +- sites/www/changelog.rst | 1 + 3 files changed, 3 insertions(+), 2 deletions(-) (limited to 'sites') diff --git a/paramiko/__init__.py b/paramiko/__init__.py index b1d9aaa9..22f1bc21 100644 --- a/paramiko/__init__.py +++ b/paramiko/__init__.py @@ -23,7 +23,7 @@ if sys.version_info < (2, 6): __author__ = "Jeff Forcier " -__version__ = "1.13.0" +__version__ = "1.13.1" __version_info__ = tuple([ int(d) for d in __version__.split(".") ]) __license__ = "GNU Lesser General Public License (LGPL)" diff --git a/setup.py b/setup.py index 4a858326..05dc98d5 100644 --- a/setup.py +++ b/setup.py @@ -56,7 +56,7 @@ if sys.platform == 'darwin': setup( name = "paramiko", - version = "1.13.0", + version = "1.13.1", description = "SSH2 protocol library", long_description = longdesc, author = "Jeff Forcier", diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst index fbb3270f..a652e565 100644 --- a/sites/www/changelog.rst +++ b/sites/www/changelog.rst @@ -2,6 +2,7 @@ Changelog ========= +* :release:`1.13.1 <2014-05-07>` * :release:`1.12.4 <2014-05-07>` * :release:`1.11.6 <2014-05-07>` * :bug:`-` `paramiko.file.BufferedFile.read` incorrectly returned text strings -- cgit v1.2.3 From 951faed80b017e553a27c4cb98f210df44341f8f Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Wed, 7 May 2014 16:13:33 -0700 Subject: Cut 1.14 --- paramiko/__init__.py | 2 +- setup.py | 2 +- sites/www/changelog.rst | 1 + 3 files changed, 3 insertions(+), 2 deletions(-) (limited to 'sites') diff --git a/paramiko/__init__.py b/paramiko/__init__.py index 22f1bc21..4c62ad4a 100644 --- a/paramiko/__init__.py +++ b/paramiko/__init__.py @@ -23,7 +23,7 @@ if sys.version_info < (2, 6): __author__ = "Jeff Forcier " -__version__ = "1.13.1" +__version__ = "1.14.0" __version_info__ = tuple([ int(d) for d in __version__.split(".") ]) __license__ = "GNU Lesser General Public License (LGPL)" diff --git a/setup.py b/setup.py index 05dc98d5..c0f1e579 100644 --- a/setup.py +++ b/setup.py @@ -56,7 +56,7 @@ if sys.platform == 'darwin': setup( name = "paramiko", - version = "1.13.1", + version = "1.14.0", description = "SSH2 protocol library", long_description = longdesc, author = "Jeff Forcier", diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst index 52fe4ff3..f8a4d2c1 100644 --- a/sites/www/changelog.rst +++ b/sites/www/changelog.rst @@ -2,6 +2,7 @@ Changelog ========= +* :release:`1.14.0 <2014-05-07>` * :release:`1.13.1 <2014-05-07>` * :release:`1.12.4 <2014-05-07>` * :release:`1.11.6 <2014-05-07>` -- cgit v1.2.3 From 6d48018d11a2058213481fdfeed8887fccc31854 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Mon, 11 Aug 2014 10:31:02 -0700 Subject: Add FAQ about nonstandard SSH implementations --- sites/www/faq.rst | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) (limited to 'sites') diff --git a/sites/www/faq.rst b/sites/www/faq.rst index a7e80014..bf450f63 100644 --- a/sites/www/faq.rst +++ b/sites/www/faq.rst @@ -7,3 +7,20 @@ Which version should I use? I see multiple active releases. Please see :ref:`the installation docs ` which have an explicit section about this topic. + +Paramiko doesn't work with my Cisco, Windows or other non-Unix system! +====================================================================== + +In an ideal world, the developers would love to support every possible target +system. Unfortunately, volunteer development time and access to non-mainstream +platforms are limited, meaning that we can only fully support standard OpenSSH +implementations such as those found on the average Linux distribution (as well +as on Mac OS X and \*BSD.) + +Because of this, **we typically close bug reports for nonstandard SSH +implementations**. + +However, **closed does not imply locked** - affected users can still post +comments on such tickets - and **we will always consider actual patch +submissions for these issues**, provided they can get +1s from similarly +affected users and are proven to not break existing functionality. -- cgit v1.2.3 From dac6952331109bdab441040cc8b0136697252297 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Mon, 11 Aug 2014 10:55:46 -0700 Subject: Make links to Github more explicit --- sites/www/contact.rst | 1 + sites/www/contributing.rst | 16 ++++++++++------ 2 files changed, 11 insertions(+), 6 deletions(-) (limited to 'sites') diff --git a/sites/www/contact.rst b/sites/www/contact.rst index 2b6583f5..7e6c947e 100644 --- a/sites/www/contact.rst +++ b/sites/www/contact.rst @@ -9,3 +9,4 @@ following ways: * Mailing list: ``paramiko@librelist.com`` (see `the LibreList homepage `_ for usage details). * This website - a blog section is forthcoming. +* Submit contributions on Github - see the :doc:`contributing` page. diff --git a/sites/www/contributing.rst b/sites/www/contributing.rst index 634c2b26..a44414e8 100644 --- a/sites/www/contributing.rst +++ b/sites/www/contributing.rst @@ -5,18 +5,22 @@ Contributing How to get the code =================== -Our primary Git repository is on Github at `paramiko/paramiko -`_; please follow their instructions for -cloning to your local system. (If you intend to submit patches/pull requests, -we recommend forking first, then cloning your fork. Github has excellent -documentation for all this.) +Our primary Git repository is on Github at `paramiko/paramiko`_; +please follow their instructions for cloning to your local system. (If you +intend to submit patches/pull requests, we recommend forking first, then +cloning your fork. Github has excellent documentation for all this.) How to submit bug reports or new code ===================================== Please see `this project-agnostic contribution guide -`_ - we follow it explicitly. +`_ - we follow it explicitly. Again, our code +repository and bug tracker is `on Github`_. Our current changelog is located in ``sites/www/changelog.rst`` - the top level files like ``ChangeLog.*`` and ``NEWS`` are historical only. + + +.. _paramiko/paramiko: +.. _on Github: https://github.com/paramiko/paramiko -- cgit v1.2.3 From 991d56bad32c1ea4eda6c86771a4a4b7bef00475 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Mon, 11 Aug 2014 11:40:20 -0700 Subject: Clarify FAQ --- sites/www/faq.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'sites') diff --git a/sites/www/faq.rst b/sites/www/faq.rst index bf450f63..a5d9b383 100644 --- a/sites/www/faq.rst +++ b/sites/www/faq.rst @@ -18,7 +18,7 @@ implementations such as those found on the average Linux distribution (as well as on Mac OS X and \*BSD.) Because of this, **we typically close bug reports for nonstandard SSH -implementations**. +implementations or host systems**. However, **closed does not imply locked** - affected users can still post comments on such tickets - and **we will always consider actual patch -- cgit v1.2.3 From d8a71fcdf0b57837632ccfa806386443fdb6dcc2 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Mon, 18 Aug 2014 18:36:59 -0700 Subject: Sphinx conf cleanup --- sites/www/conf.py | 3 --- 1 file changed, 3 deletions(-) (limited to 'sites') diff --git a/sites/www/conf.py b/sites/www/conf.py index bdb5929a..0b0fb85c 100644 --- a/sites/www/conf.py +++ b/sites/www/conf.py @@ -12,13 +12,10 @@ extensions.append('releases') releases_release_uri = "https://github.com/paramiko/paramiko/tree/v%s" releases_issue_uri = "https://github.com/paramiko/paramiko/issues/%s" -# Intersphinx for referencing API/usage docs -extensions.append('sphinx.ext.intersphinx') # Default is 'local' building, but reference the public docs site when building # under RTD. target = join(dirname(__file__), '..', 'docs', '_build') if os.environ.get('READTHEDOCS') == 'True': - # TODO: switch to docs.paramiko.org post go-live of sphinx API docs target = 'http://docs.paramiko.org/en/latest/' intersphinx_mapping['docs'] = (target, None) -- cgit v1.2.3 From 178e43060c52b9f65026a5ec57bbe5fae166ba4e Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Thu, 21 Aug 2014 09:28:58 -0700 Subject: This isn't worth having and then always forgetting about --- sites/www/installing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'sites') diff --git a/sites/www/installing.rst b/sites/www/installing.rst index a28ce6cd..546aad9d 100644 --- a/sites/www/installing.rst +++ b/sites/www/installing.rst @@ -32,7 +32,7 @@ Release lines Users desiring stability may wish to pin themselves to a specific release line once they first start using Paramiko; to assist in this, we guarantee bugfixes -for at least the last 2-3 releases including the latest stable one. This currently means Paramiko **1.11** through **1.13**. +for at least the last 2-3 releases including the latest stable one. If you're unsure which version to install, we have suggestions: -- cgit v1.2.3 From e941d56e8a385f4f2ef5c0e9a77e66c844b5a729 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Thu, 21 Aug 2014 09:30:12 -0700 Subject: More tweaks - don't make it sound like we routinely support >3, we don't --- sites/www/installing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'sites') diff --git a/sites/www/installing.rst b/sites/www/installing.rst index 546aad9d..729147c5 100644 --- a/sites/www/installing.rst +++ b/sites/www/installing.rst @@ -32,7 +32,7 @@ Release lines Users desiring stability may wish to pin themselves to a specific release line once they first start using Paramiko; to assist in this, we guarantee bugfixes -for at least the last 2-3 releases including the latest stable one. +for the last 2-3 releases including the latest stable one. If you're unsure which version to install, we have suggestions: -- cgit v1.2.3 From 2a88241ea7ed3facf730678ef28a8281903cf9a9 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Mon, 25 Aug 2014 16:27:15 -0700 Subject: Add a plus to our 3.3 support to denote 3.4 and on --- sites/www/installing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'sites') diff --git a/sites/www/installing.rst b/sites/www/installing.rst index 729147c5..052825c4 100644 --- a/sites/www/installing.rst +++ b/sites/www/installing.rst @@ -16,7 +16,7 @@ via `pip `_:: Users who want the bleeding edge can install the development version via ``pip install paramiko==dev``. -We currently support **Python 2.6, 2.7 and 3.3** (Python **3.2** should also +We currently support **Python 2.6, 2.7 and 3.3+** (Python **3.2** should also work but has a less-strong compatibility guarantee from us.) Users on Python 2.5 or older are urged to upgrade. -- cgit v1.2.3 From 5d010cd8c496e1ed7e13e7110f7fca9632c08e47 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Mon, 25 Aug 2014 16:28:02 -0700 Subject: Changelog re #371 --- sites/www/changelog.rst | 2 ++ 1 file changed, 2 insertions(+) (limited to 'sites') diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst index f8a4d2c1..5ed0c961 100644 --- a/sites/www/changelog.rst +++ b/sites/www/changelog.rst @@ -2,6 +2,8 @@ Changelog ========= +* :support:`371` Add Travis support & docs update for Python 3.4. Thanks to + Olle Lundberg. * :release:`1.14.0 <2014-05-07>` * :release:`1.13.1 <2014-05-07>` * :release:`1.12.4 <2014-05-07>` -- cgit v1.2.3 From fd1e162243898e34545ef5c1985bedee16174981 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Mon, 25 Aug 2014 21:59:59 -0700 Subject: Changelog re #285, re #352 --- sites/www/changelog.rst | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'sites') diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst index 5ed0c961..2e2d2f63 100644 --- a/sites/www/changelog.rst +++ b/sites/www/changelog.rst @@ -2,6 +2,12 @@ Changelog ========= +* :bug:`285` (also :issue:`352`) Update our Python 3 ``b()`` compatibility shim + to handle ``buffer`` objects correctly; this fixes a frequently reported + issue affecting many users, including users of the ``bzr`` software suite. + Thanks to ``@basictheprogram`` for the initial report, Jelmer Vernooij for + the fix and Andrew Starr-Bochicchio & Jeremy T. Bouse (among others) for + discussion & feedback. * :support:`371` Add Travis support & docs update for Python 3.4. Thanks to Olle Lundberg. * :release:`1.14.0 <2014-05-07>` -- cgit v1.2.3 From d05ca17db876055a5f584e720b1b0733116b4365 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Mon, 25 Aug 2014 21:59:59 -0700 Subject: Changelog re #285, re #352 Conflicts: sites/www/changelog.rst --- sites/www/changelog.rst | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'sites') diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst index a652e565..5c8e02f4 100644 --- a/sites/www/changelog.rst +++ b/sites/www/changelog.rst @@ -2,6 +2,12 @@ Changelog ========= +* :bug:`285` (also :issue:`352`) Update our Python 3 ``b()`` compatibility shim + to handle ``buffer`` objects correctly; this fixes a frequently reported + issue affecting many users, including users of the ``bzr`` software suite. + Thanks to ``@basictheprogram`` for the initial report, Jelmer Vernooij for + the fix and Andrew Starr-Bochicchio & Jeremy T. Bouse (among others) for + discussion & feedback. * :release:`1.13.1 <2014-05-07>` * :release:`1.12.4 <2014-05-07>` * :release:`1.11.6 <2014-05-07>` -- cgit v1.2.3 From 87f6f56196b0b384c906db96ef5593c5cb6a0c61 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Mon, 25 Aug 2014 22:26:33 -0700 Subject: Changelog re #169 --- sites/www/changelog.rst | 2 ++ 1 file changed, 2 insertions(+) (limited to 'sites') diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst index 5c8e02f4..b9d0df0b 100644 --- a/sites/www/changelog.rst +++ b/sites/www/changelog.rst @@ -2,6 +2,8 @@ Changelog ========= +* :support:`169 backported` Minor refactor of + `paramiko.sftp_client.SFTPClient.put` thanks to Abhinav Upadhyay. * :bug:`285` (also :issue:`352`) Update our Python 3 ``b()`` compatibility shim to handle ``buffer`` objects correctly; this fixes a frequently reported issue affecting many users, including users of the ``bzr`` software suite. -- cgit v1.2.3 From 5fc6969e23ec5e013f432e4efbe12d771150c1e1 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Mon, 25 Aug 2014 22:32:21 -0700 Subject: Fix docstrings re: addition of `getfo`/`putfo`, closes #229 --- paramiko/sftp_client.py | 8 ++------ sites/www/changelog.rst | 2 ++ 2 files changed, 4 insertions(+), 6 deletions(-) (limited to 'sites') diff --git a/paramiko/sftp_client.py b/paramiko/sftp_client.py index cbef8f71..2ff2d51d 100644 --- a/paramiko/sftp_client.py +++ b/paramiko/sftp_client.py @@ -534,9 +534,7 @@ class SFTPClient(BaseSFTP): an `.SFTPAttributes` object containing attributes about the given file. - .. versionadded:: 1.4 - .. versionchanged:: 1.7.4 - Began returning rich attribute objects. + .. versionadded:: 1.10 """ with self.file(remotepath, 'wb') as fr: fr.set_pipelined(True) @@ -601,9 +599,7 @@ class SFTPClient(BaseSFTP): the bytes transferred so far and the total bytes to be transferred :return: the `number ` of bytes written to the opened file object - .. versionadded:: 1.4 - .. versionchanged:: 1.7.4 - Added the ``callable`` param. + .. versionadded:: 1.10 """ with self.open(remotepath, 'rb') as fr: file_size = self.stat(remotepath).st_size diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst index b9d0df0b..cdd513f4 100644 --- a/sites/www/changelog.rst +++ b/sites/www/changelog.rst @@ -2,6 +2,8 @@ Changelog ========= +* :support:`229` Fix a couple of incorrectly-copied docstrings' ``.. + versionadded::`` RST directives. Thanks to Aarni Koskela for the catch. * :support:`169 backported` Minor refactor of `paramiko.sftp_client.SFTPClient.put` thanks to Abhinav Upadhyay. * :bug:`285` (also :issue:`352`) Update our Python 3 ``b()`` compatibility shim -- cgit v1.2.3 From 12e752d11aa22ee6ba959115725e386ca779c1cb Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Mon, 25 Aug 2014 22:44:54 -0700 Subject: Rework re #239 to work off post-1.13 codebase. Closes #239 --- paramiko/config.py | 2 +- sites/www/changelog.rst | 2 ++ tests/test_util.py | 6 ++++++ 3 files changed, 9 insertions(+), 1 deletion(-) (limited to 'sites') diff --git a/paramiko/config.py b/paramiko/config.py index 77fa13d7..f650ee24 100644 --- a/paramiko/config.py +++ b/paramiko/config.py @@ -55,7 +55,7 @@ class SSHConfig (object): """ host = {"host": ['*'], "config": {}} for line in file_obj: - line = line.rstrip('\n').lstrip() + line = line.rstrip('\r\n').lstrip() if (line == '') or (line[0] == '#'): continue if '=' in line: diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst index cdd513f4..903e6378 100644 --- a/sites/www/changelog.rst +++ b/sites/www/changelog.rst @@ -2,6 +2,8 @@ Changelog ========= +* :bug:`239` Add Windows-style CRLF support to SSH config file parsing. Props + to Christopher Swenson. * :support:`229` Fix a couple of incorrectly-copied docstrings' ``.. versionadded::`` RST directives. Thanks to Aarni Koskela for the catch. * :support:`169 backported` Minor refactor of diff --git a/tests/test_util.py b/tests/test_util.py index 6bde4045..ecf8db72 100644 --- a/tests/test_util.py +++ b/tests/test_util.py @@ -338,3 +338,9 @@ IdentityFile something_%l_using_fqdn """ config = paramiko.util.parse_ssh_config(StringIO(test_config)) assert config.lookup('meh') # will die during lookup() if bug regresses + + def test_13_config_dos_crlf_succeeds(self): + config_file = StringIO("host abcqwerty\r\nHostName 127.0.0.1\r\n") + config = paramiko.SSHConfig() + config.parse(config_file) + self.assertEqual(config.lookup("abcqwerty")["hostname"], "127.0.0.1") -- cgit v1.2.3 From 118d581f92b1aa49a482c68faa73df0c8967b3c4 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Mon, 25 Aug 2014 22:58:58 -0700 Subject: Changelog re #272 --- sites/www/changelog.rst | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'sites') diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst index 903e6378..99115727 100644 --- a/sites/www/changelog.rst +++ b/sites/www/changelog.rst @@ -2,6 +2,10 @@ Changelog ========= +* :bug:`272` Fix a bug where ``known_hosts`` parsing hashed the input hostname + as well as the hostnames from the ``known_hosts`` file, on every comparison. + Thanks to ``@sigmunau`` for final patch and ``@ostacey`` for the original + report. * :bug:`239` Add Windows-style CRLF support to SSH config file parsing. Props to Christopher Swenson. * :support:`229` Fix a couple of incorrectly-copied docstrings' ``.. -- cgit v1.2.3 From c7ffe1718a3bae232b7ecef959545dac9f729095 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Mon, 25 Aug 2014 23:07:57 -0700 Subject: Changelog re #312, closes #312 --- sites/www/changelog.rst | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'sites') diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst index 99115727..b315b0d7 100644 --- a/sites/www/changelog.rst +++ b/sites/www/changelog.rst @@ -2,6 +2,10 @@ Changelog ========= +* :bug:`312` `paramiko.transport.Transport` had a bug in its ``__repr__`` which + surfaces during errors encountered within its ``__init__``, causing + problematic tracebacks in such situations. Thanks to Simon Percivall for + catch & patch. * :bug:`272` Fix a bug where ``known_hosts`` parsing hashed the input hostname as well as the hostnames from the ``known_hosts`` file, on every comparison. Thanks to ``@sigmunau`` for final patch and ``@ostacey`` for the original -- cgit v1.2.3 From 77919c6c25d9016c74537ea9b901cedc19050983 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Mon, 25 Aug 2014 23:15:22 -0700 Subject: Changelog re #324, closes #324 --- sites/www/changelog.rst | 2 ++ 1 file changed, 2 insertions(+) (limited to 'sites') diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst index b315b0d7..6979b97e 100644 --- a/sites/www/changelog.rst +++ b/sites/www/changelog.rst @@ -2,6 +2,8 @@ Changelog ========= +* :support:`324 backported` A bevvy of documentation typo fixes, courtesy of Roy + Wellington. * :bug:`312` `paramiko.transport.Transport` had a bug in its ``__repr__`` which surfaces during errors encountered within its ``__init__``, causing problematic tracebacks in such situations. Thanks to Simon Percivall for -- cgit v1.2.3 From 3908baad6e1d6d4fc62da24111cd466ce5cb9a88 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Mon, 25 Aug 2014 23:34:13 -0700 Subject: Changelog re #376, closes #376 --- sites/www/changelog.rst | 3 +++ 1 file changed, 3 insertions(+) (limited to 'sites') diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst index 6979b97e..9258cfec 100644 --- a/sites/www/changelog.rst +++ b/sites/www/changelog.rst @@ -2,6 +2,9 @@ Changelog ========= +* :bug:`376` Be less aggressive about expanding variables in ``ssh_config`` + files, which results in a speedup of SSH config parsing. Credit to Olle + Lundberg. * :support:`324 backported` A bevvy of documentation typo fixes, courtesy of Roy Wellington. * :bug:`312` `paramiko.transport.Transport` had a bug in its ``__repr__`` which -- cgit v1.2.3 From 1b69e0f4095883ef3f282552fde12dfb00ebdda4 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Mon, 25 Aug 2014 23:42:21 -0700 Subject: Cut 1.13.2 --- paramiko/__init__.py | 2 +- setup.py | 2 +- sites/www/changelog.rst | 1 + 3 files changed, 3 insertions(+), 2 deletions(-) (limited to 'sites') diff --git a/paramiko/__init__.py b/paramiko/__init__.py index 22f1bc21..d86b868b 100644 --- a/paramiko/__init__.py +++ b/paramiko/__init__.py @@ -23,7 +23,7 @@ if sys.version_info < (2, 6): __author__ = "Jeff Forcier " -__version__ = "1.13.1" +__version__ = "1.13.2" __version_info__ = tuple([ int(d) for d in __version__.split(".") ]) __license__ = "GNU Lesser General Public License (LGPL)" diff --git a/setup.py b/setup.py index 05dc98d5..082a843e 100644 --- a/setup.py +++ b/setup.py @@ -56,7 +56,7 @@ if sys.platform == 'darwin': setup( name = "paramiko", - version = "1.13.1", + version = "1.13.2", description = "SSH2 protocol library", long_description = longdesc, author = "Jeff Forcier", diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst index 9258cfec..9c519c03 100644 --- a/sites/www/changelog.rst +++ b/sites/www/changelog.rst @@ -2,6 +2,7 @@ Changelog ========= +* :release:`1.13.2 <2014-08-25>` * :bug:`376` Be less aggressive about expanding variables in ``ssh_config`` files, which results in a speedup of SSH config parsing. Credit to Olle Lundberg. -- cgit v1.2.3 From d7b93df7aaf9f409da7578a107829c138d042121 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Mon, 25 Aug 2014 23:43:48 -0700 Subject: Cut 1.14.1 --- paramiko/__init__.py | 2 +- setup.py | 2 +- sites/www/changelog.rst | 1 + 3 files changed, 3 insertions(+), 2 deletions(-) (limited to 'sites') diff --git a/paramiko/__init__.py b/paramiko/__init__.py index 4c62ad4a..2ebc8a65 100644 --- a/paramiko/__init__.py +++ b/paramiko/__init__.py @@ -23,7 +23,7 @@ if sys.version_info < (2, 6): __author__ = "Jeff Forcier " -__version__ = "1.14.0" +__version__ = "1.14.1" __version_info__ = tuple([ int(d) for d in __version__.split(".") ]) __license__ = "GNU Lesser General Public License (LGPL)" diff --git a/setup.py b/setup.py index c0f1e579..38e444f5 100644 --- a/setup.py +++ b/setup.py @@ -56,7 +56,7 @@ if sys.platform == 'darwin': setup( name = "paramiko", - version = "1.14.0", + version = "1.14.1", description = "SSH2 protocol library", long_description = longdesc, author = "Jeff Forcier", diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst index c4c1e698..0fcde10f 100644 --- a/sites/www/changelog.rst +++ b/sites/www/changelog.rst @@ -2,6 +2,7 @@ Changelog ========= +* :release:`1.14.1 <2014-08-25>` * :release:`1.13.2 <2014-08-25>` * :bug:`376` Be less aggressive about expanding variables in ``ssh_config`` files, which results in a speedup of SSH config parsing. Credit to Olle -- cgit v1.2.3 From 28b7db145fed32840f8d2edea8fdce27dc00ca26 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Mon, 25 Aug 2014 23:48:28 -0700 Subject: Consolidate version info. Closes #249 --- paramiko/__init__.py | 3 +-- paramiko/_version.py | 2 ++ setup.py | 9 ++++++++- sites/www/changelog.rst | 2 ++ 4 files changed, 13 insertions(+), 3 deletions(-) create mode 100644 paramiko/_version.py (limited to 'sites') diff --git a/paramiko/__init__.py b/paramiko/__init__.py index 2ebc8a65..65f6f8a2 100644 --- a/paramiko/__init__.py +++ b/paramiko/__init__.py @@ -17,14 +17,13 @@ # 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA. import sys +from paramiko._version import __version__, __version_info__ if sys.version_info < (2, 6): raise RuntimeError('You need Python 2.6+ for this module.') __author__ = "Jeff Forcier " -__version__ = "1.14.1" -__version_info__ = tuple([ int(d) for d in __version__.split(".") ]) __license__ = "GNU Lesser General Public License (LGPL)" diff --git a/paramiko/_version.py b/paramiko/_version.py new file mode 100644 index 00000000..a7857b09 --- /dev/null +++ b/paramiko/_version.py @@ -0,0 +1,2 @@ +__version_info__ = (1, 15, 0) +__version__ = '.'.join(map(str, __version_info__)) diff --git a/setup.py b/setup.py index 3d8268d1..13386c8e 100644 --- a/setup.py +++ b/setup.py @@ -54,9 +54,16 @@ if sys.platform == 'darwin': setup_helper.install_custom_make_tarball() +# Version info -- read without importing +_locals = {} +with open('paramiko/_version.py') as fp: + exec(fp.read(), None, _locals) +version = _locals['__version__'] + + setup( name = "paramiko", - version = "1.14.1", + version = version, description = "SSH2 protocol library", long_description = longdesc, author = "Jeff Forcier", diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst index 089ec30e..b6fa7ccc 100644 --- a/sites/www/changelog.rst +++ b/sites/www/changelog.rst @@ -2,6 +2,8 @@ Changelog ========= +* :support:`249` Consolidate version information into one spot. Thanks to Gabi + Davar for the reminder. * :release:`1.14.1 <2014-08-25>` * :release:`1.13.2 <2014-08-25>` * :bug:`376` Be less aggressive about expanding variables in ``ssh_config`` -- cgit v1.2.3 From 9014c735fc94d133c5d9aada93d43f1f5d1145f2 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Tue, 26 Aug 2014 00:14:02 -0700 Subject: Forgot to mark one support-bug as backported --- sites/www/changelog.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'sites') diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst index 9c519c03..1ca3dfef 100644 --- a/sites/www/changelog.rst +++ b/sites/www/changelog.rst @@ -18,7 +18,7 @@ Changelog report. * :bug:`239` Add Windows-style CRLF support to SSH config file parsing. Props to Christopher Swenson. -* :support:`229` Fix a couple of incorrectly-copied docstrings' ``.. +* :support:`229 backported` Fix a couple of incorrectly-copied docstrings' ``.. versionadded::`` RST directives. Thanks to Aarni Koskela for the catch. * :support:`169 backported` Minor refactor of `paramiko.sftp_client.SFTPClient.put` thanks to Abhinav Upadhyay. -- cgit v1.2.3 From b641c69a80e2bd4737c636e7edd0918d6753c3d0 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Tue, 26 Aug 2014 12:50:10 -0700 Subject: Backport #378 to 1.13, closes #378 --- paramiko/config.py | 12 +++++++----- sites/www/changelog.rst | 2 ++ 2 files changed, 9 insertions(+), 5 deletions(-) (limited to 'sites') diff --git a/paramiko/config.py b/paramiko/config.py index 96ec9ef7..30e000e7 100644 --- a/paramiko/config.py +++ b/paramiko/config.py @@ -56,7 +56,7 @@ class SSHConfig (object): host = {"host": ['*'], "config": {}} for line in file_obj: line = line.rstrip('\r\n').lstrip() - if (line == '') or (line[0] == '#'): + if not line or line.startswith('#'): continue if '=' in line: # Ensure ProxyCommand gets properly split @@ -90,7 +90,7 @@ class SSHConfig (object): else: host['config'][key] = [value] elif key not in host['config']: - host['config'].update({key: value}) + host['config'][key] = value self._config.append(host) def lookup(self, hostname): @@ -111,8 +111,10 @@ class SSHConfig (object): :param str hostname: the hostname to lookup """ - matches = [config for config in self._config if - self._allowed(hostname, config['host'])] + matches = [ + config for config in self._config + if self._allowed(config['host'], hostname) + ] ret = {} for match in matches: @@ -128,7 +130,7 @@ class SSHConfig (object): ret = self._expand_variables(ret, hostname) return ret - def _allowed(self, hostname, hosts): + def _allowed(self, hosts, hostname): match = False for host in hosts: if host.startswith('!') and fnmatch.fnmatch(hostname, host[1:]): diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst index 1ca3dfef..0cbc933f 100644 --- a/sites/www/changelog.rst +++ b/sites/www/changelog.rst @@ -2,6 +2,8 @@ Changelog ========= +* :support:`378 backported` Minor code cleanup in the SSH config module + courtesy of Olle Lundberg. * :release:`1.13.2 <2014-08-25>` * :bug:`376` Be less aggressive about expanding variables in ``ssh_config`` files, which results in a speedup of SSH config parsing. Credit to Olle -- cgit v1.2.3 From 162eebf704b5111d34f430488868d3185d51ba21 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Mon, 25 Aug 2014 23:48:28 -0700 Subject: Consolidate version info. Closes #249 Conflicts: paramiko/__init__.py setup.py sites/www/changelog.rst --- paramiko/__init__.py | 3 +-- paramiko/_version.py | 2 ++ setup.py | 9 ++++++++- sites/www/changelog.rst | 2 ++ 4 files changed, 13 insertions(+), 3 deletions(-) create mode 100644 paramiko/_version.py (limited to 'sites') diff --git a/paramiko/__init__.py b/paramiko/__init__.py index d86b868b..65f6f8a2 100644 --- a/paramiko/__init__.py +++ b/paramiko/__init__.py @@ -17,14 +17,13 @@ # 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA. import sys +from paramiko._version import __version__, __version_info__ if sys.version_info < (2, 6): raise RuntimeError('You need Python 2.6+ for this module.') __author__ = "Jeff Forcier " -__version__ = "1.13.2" -__version_info__ = tuple([ int(d) for d in __version__.split(".") ]) __license__ = "GNU Lesser General Public License (LGPL)" diff --git a/paramiko/_version.py b/paramiko/_version.py new file mode 100644 index 00000000..0402fcf2 --- /dev/null +++ b/paramiko/_version.py @@ -0,0 +1,2 @@ +__version_info__ = (1, 13, 3) +__version__ = '.'.join(map(str, __version_info__)) diff --git a/setup.py b/setup.py index 082a843e..235fd0e3 100644 --- a/setup.py +++ b/setup.py @@ -54,9 +54,16 @@ if sys.platform == 'darwin': setup_helper.install_custom_make_tarball() +# Version info -- read without importing +_locals = {} +with open('paramiko/_version.py') as fp: + exec(fp.read(), None, _locals) +version = _locals['__version__'] + + setup( name = "paramiko", - version = "1.13.2", + version = version, description = "SSH2 protocol library", long_description = longdesc, author = "Jeff Forcier", diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst index 0cbc933f..0f79775c 100644 --- a/sites/www/changelog.rst +++ b/sites/www/changelog.rst @@ -4,6 +4,8 @@ Changelog * :support:`378 backported` Minor code cleanup in the SSH config module courtesy of Olle Lundberg. +* :support:`249` Consolidate version information into one spot. Thanks to Gabi + Davar for the reminder. * :release:`1.13.2 <2014-08-25>` * :bug:`376` Be less aggressive about expanding variables in ``ssh_config`` files, which results in a speedup of SSH config parsing. Credit to Olle -- cgit v1.2.3 From 43c5cdaa3094c59718c8df69b1de834aee15485c Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Fri, 5 Sep 2014 10:12:40 -0700 Subject: s/gittip/gratipay/ --- dev-requirements.txt | 2 +- sites/shared_conf.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) (limited to 'sites') diff --git a/dev-requirements.txt b/dev-requirements.txt index a21a48ed..7a0ccbc5 100644 --- a/dev-requirements.txt +++ b/dev-requirements.txt @@ -4,6 +4,6 @@ tox>=1.4,<1.5 invoke>=0.7.0,<0.8 invocations>=0.5.0 sphinx>=1.1.3 -alabaster>=0.4.0 +alabaster>=0.6.1 releases>=0.5.2 wheel==0.23.0 diff --git a/sites/shared_conf.py b/sites/shared_conf.py index 69908388..4a6a5c4e 100644 --- a/sites/shared_conf.py +++ b/sites/shared_conf.py @@ -12,7 +12,7 @@ html_theme_options = { 'description': "A Python implementation of SSHv2.", 'github_user': 'paramiko', 'github_repo': 'paramiko', - 'gittip_user': 'bitprophet', + 'gratipay_user': 'bitprophet', 'analytics_id': 'UA-18486793-2', 'travis_button': True, } -- cgit v1.2.3