From: Kenneth Reitz Date: Mon, 15 Aug 2011 02:07:15 +0000 (-0400) Subject: massive documentation update X-Git-Tag: v0.6.0~61 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=d50742f059ee40abb1d410c3b0d1115a8ea8d8fb;p=services%2Fpython-requests.git massive documentation update --- diff --git a/docs/community/faq.rst b/docs/community/faq.rst new file mode 100644 index 0000000..2ccb6a7 --- /dev/null +++ b/docs/community/faq.rst @@ -0,0 +1,43 @@ +.. _faq: + +Frequently Asked Questions +========================== + +This part of the documentation covers common questions about Requests. + +Why not Httplib2? +----------------- + +Chris Adams gave an excellent summary on +`Hacker News `_: + + httplib2 is part of why you should use requests: it's far more respectable + as a client but not as well documented and it still takes way too much code + for basic operations. I appreciate what httplib2 is trying to do, that + there's a ton of hard low-level annoyances in building a modern HTTP + client, but really, just use requests instead. Kenneth Reitz is very + motivated and he gets the degree to which simple things should be simple + whereas httplib2 feels more like an academic exercise than something + people should use to build production systems[1]. + + Disclosure: I'm listed in the requests AUTHORS file but can claim credit + for, oh, about 0.0001% of the awesomeness. + + 1. http://code.google.com/p/httplib2/issues/detail?id=96 is a good example: + an annoying bug which affect many people, there was a fix available for + months, which worked great when I applied it in a fork and pounded a couple + TB of data through it, but it took over a year to make it into trunk and + even longer to make it onto PyPI where any other project which required " + httplib2" would get the working version. + + +Python 3 Support? +----------------- + +It's on the way. + + +Keep-alive Support? +------------------- + +It's on the way. \ No newline at end of file diff --git a/docs/community/support.rst b/docs/community/support.rst new file mode 100644 index 0000000..53f3c81 --- /dev/null +++ b/docs/community/support.rst @@ -0,0 +1,37 @@ +.. _support: + +Support +======= + +If you have a questions or issues about Requests, there are serveral options: + +Send a Tweet +------------ + +If your question is less than 140 characters, feel free to send a tweet to +`@kennethreitz `_. + + +File an Issue +------------- + +If you notice some unexpected behavior in Requests, or want to see support +for a new feature, +`file an issue on GitHub `_. + + +E-mail +------ + +I'm more than happy to answer any personal or in-depth questions about +Requests. Feel free to email +`requests@kennethreitz.com `_. + + +IRC +--- + +The official Freenode channel for Requests is +`#python-requests `_ + +I'm also available as **kennethreitz** on Freenode. \ No newline at end of file diff --git a/docs/community/updates.rst b/docs/community/updates.rst new file mode 100644 index 0000000..942ccac --- /dev/null +++ b/docs/community/updates.rst @@ -0,0 +1,31 @@ +.. _updates: + +Updates +======= + +If you'd like to stay up to date on the community and development of Requests, +there are serveral options: + +GitHub +------ + +The best way to track the development of Requests is through +`the GitHub repo `_. + +Twitter +------- + +I often tweet about new features and releases of Requests. + +Follow `@kennethreitz `_ for updates. + + + +Mailing List +------------ + +There's a low-volume mailing list for Requests. To subscribe to the +mailing list, send an email to +`requests@librelist.org `_. + + diff --git a/docs/dev/authors.rst b/docs/dev/authors.rst new file mode 100644 index 0000000..5b3cc85 --- /dev/null +++ b/docs/dev/authors.rst @@ -0,0 +1,5 @@ +Authors +======= + + +.. include:: ../../AUTHORS \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index e2bc2b9..8bef62b 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -69,11 +69,23 @@ instructions for getting the most out of Requests. user/intro user/install - user/faq -.. user/quickstart + user/quickstart user/advanced +Community Guide +----------------- + +This part of the documentation, which is mostly prose, details the +Requests ecosystem and community. + +.. toctree:: + :maxdepth: 2 + + community/faq + community/support + community/updates + API Documentation ----------------- @@ -97,3 +109,4 @@ you. dev/internals dev/todo + dev/authors diff --git a/docs/user/faq.rst b/docs/user/faq.rst deleted file mode 100644 index 2ccb6a7..0000000 --- a/docs/user/faq.rst +++ /dev/null @@ -1,43 +0,0 @@ -.. _faq: - -Frequently Asked Questions -========================== - -This part of the documentation covers common questions about Requests. - -Why not Httplib2? ------------------ - -Chris Adams gave an excellent summary on -`Hacker News `_: - - httplib2 is part of why you should use requests: it's far more respectable - as a client but not as well documented and it still takes way too much code - for basic operations. I appreciate what httplib2 is trying to do, that - there's a ton of hard low-level annoyances in building a modern HTTP - client, but really, just use requests instead. Kenneth Reitz is very - motivated and he gets the degree to which simple things should be simple - whereas httplib2 feels more like an academic exercise than something - people should use to build production systems[1]. - - Disclosure: I'm listed in the requests AUTHORS file but can claim credit - for, oh, about 0.0001% of the awesomeness. - - 1. http://code.google.com/p/httplib2/issues/detail?id=96 is a good example: - an annoying bug which affect many people, there was a fix available for - months, which worked great when I applied it in a fork and pounded a couple - TB of data through it, but it took over a year to make it into trunk and - even longer to make it onto PyPI where any other project which required " - httplib2" would get the working version. - - -Python 3 Support? ------------------ - -It's on the way. - - -Keep-alive Support? -------------------- - -It's on the way. \ No newline at end of file diff --git a/docs/user/quickstart.rst b/docs/user/quickstart.rst index fea0766..75ea128 100644 --- a/docs/user/quickstart.rst +++ b/docs/user/quickstart.rst @@ -1,84 +1,54 @@ -Feature Overview -================ - -Requests is designed to solve a 90% use case — making simple requests. While most -HTTP libraries are extremely extensible, they often attempt to support the entire HTTP Spec. -This often leads to extremely messy and cumbersome APIs, as is the case with urllib2. Requests abandons support for edge-cases, and focuses on the essentials. - - -.. _features: - -Requests Can: -------------- - -- Make **GET**, **POST**, **PUT**, **DELETE**, and **HEAD** requests. -- Handle HTTP and HTTPS Requests -- Add Request headers (with a simple dictionary) -- URLEncode your Form Data (with a simple dictionary) -- Add Multi-part File Uploads (with a simple dictionary) -- Handle CookieJars (with a single parameter) -- Add HTTP Authentication (with a single parameter) -- Handle redirects (with history) -- Automatically decompress GZip'd responses -- Support Unicode URLs -- Gracefully timeout -- Interface with Eventlet & Gevent - - -Requests Can't: ---------------- - -- Handle Caching -- Handle Keep-Alives - +.. _quickstart: Quickstart ========== +.. module:: requests -GET Request ------------ - - -Adding Parameters ------------------ - +Eager to get started? This page gives a good introduction in how to get started with Requests. This assumes you already have Tablib installed. If you do not, head over to the :ref:`Installation ` section. +First, make sure that: -Adding Headers --------------- +* Tablib is :ref:`installed ` +* Tablib is :ref:`up-to-date ` +Lets gets started with some simple use cases and examples. -HTTP Basic Auth ---------------- - -Tracking Redirects +Make a GET Request ------------------ +Making a standard request with Requests is very simple. +Let's get GitHub's public timeline :: + r = requests.get('https://github.com/timeline.json') -HTTP POST (Form Data) ---------------------- +Now, we have a :class:`Response` object. We can get all the information +we need from this. -HTTP POST (Binary Data) ------------------------ +Response Content +---------------- +We can read the content of the server's response:: -HTTP POST (Multipart Files) ---------------------------- + >>> r.content + '[{"repository":{"open_issues":0,"url":"https://github.com/... -HTTP PUT --------- +Response Status Codes +--------------------- + +We can check the response status code:: -HTTP DELETE ------------ + >>> r.status_code + 200 +Requests also comes with a built-in status code lookup object for easy +reference:: -HTTP HEAD ---------- + >>> r.status_code == requests.codes.ok + True \ No newline at end of file