From d50742f059ee40abb1d410c3b0d1115a8ea8d8fb Mon Sep 17 00:00:00 2001 From: Kenneth Reitz Date: Sun, 14 Aug 2011 22:07:15 -0400 Subject: [PATCH] massive documentation update --- docs/{user => community}/faq.rst | 0 docs/community/support.rst | 37 ++++++++++++ docs/community/updates.rst | 31 ++++++++++ docs/dev/authors.rst | 5 ++ docs/index.rst | 17 +++++- docs/user/quickstart.rst | 100 +++++++++++-------------------- 6 files changed, 123 insertions(+), 67 deletions(-) rename docs/{user => community}/faq.rst (100%) create mode 100644 docs/community/support.rst create mode 100644 docs/community/updates.rst create mode 100644 docs/dev/authors.rst 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 00000000..53f3c819 --- /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 00000000..942ccac1 --- /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 00000000..5b3cc85b --- /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 e2bc2b92..8bef62bb 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 fea07662..75ea128a 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 ------------ +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: + +* Tablib is :ref:`installed ` +* Tablib is :ref:`up-to-date ` -Adding Parameters ------------------ +Lets gets started with some simple use cases and examples. - -Adding Headers --------------- - - - -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') + +Now, we have a :class:`Response` object. We can get all the information +we need from this. + + +Response Content +---------------- + +We can read the content of the server's response:: + + >>> r.content + '[{"repository":{"open_issues":0,"url":"https://github.com/... -HTTP POST (Form Data) +Response Status Codes --------------------- +We can check the response status code:: -HTTP POST (Binary Data) ------------------------ + >>> r.status_code + 200 +Requests also comes with a built-in status code lookup object for easy +reference:: -HTTP POST (Multipart Files) ---------------------------- - - -HTTP PUT --------- - - -HTTP DELETE ------------ - - -HTTP HEAD ---------- + >>> r.status_code == requests.codes.ok + True \ No newline at end of file