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/user/faq.rst b/docs/community/faq.rst similarity index 100% rename from docs/user/faq.rst rename to docs/community/faq.rst 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/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