diff --git a/MANIFEST.in b/MANIFEST.in index 24d1714..c216676 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -1,4 +1,3 @@ -include README.rst +include README.markdown include LICENSE include *.txt -recursive-include docs *.txt diff --git a/README.markdown b/README.markdown new file mode 100644 index 0000000..d8fe796 --- /dev/null +++ b/README.markdown @@ -0,0 +1,229 @@ +--- +title: "sanetime: a sane date/time python interface" +--- + +#sanetime + +**A sane date/time python interface** + +better epoch time, timezones, and deltas, django support as well + +##intro + +**sanetime** was written to DRY up all the common date/time manipulations we all do constantly in our code while offering the most simple, versatile, and intuitive client possible. + +We've all learned that the only sane way to store times is using epoch time. (You have, haven't you?) +Unfortunately, manipulating epoch time and timezones with the standard python toolset requires getting up to speed on a managerie of python modules and concepts: datetime, date, time, calendar, pytz, dateutils, timedelta, time tuples, localize, normalize. + +**sanetime** seeks to bring a more sanity to the manipulations of epoch time, timezone, time delta, and time generally. + +~~~ python +>>> from sanetime import time,delta # a tiny taste + +>>> time('2012-05-01 22:31',tz='America/New_York').millis +1335925860000 + +>>> str(time(tz='Europe/London')) # now in London +'2012-05-29 15:28:05.178741 +Europe/London' + +>>> (time(2012,6,1) - time('2012-05-01')).hours +744 + +>>> (time() + delta(h=12)).s # epoch seconds 12 hours from now +1338344977 +~~~ + + +##time + +###concept + +The `time` class represents a moment in time, internally stored as microseconds since epoch. +A `time` object also has an associated timezone (UTC by default), however the timezone will never be considered during hashing, comparison or equality checks, i.e. +A moment in `time` experienced in America/New\_York is equal to the same moment in `time` experienced in Europe/Dublin. + +###methods + +####construction + +You can construct a sanetime object from epoch times, datetimes, date/time parts, or from a parseable string. + +Epoch microseconds are assumed when no keyword is given. +Intuitive aliases exists for kwargs, be as terse or verbose as you want (us = micros = epoch_micros = epoch_microseconds): + + >>> time(1338508800000000) + SaneTime(1338508800000000,) + + >>> time(micros=1338508800000000) + SaneTime(1338508800000000,) + + >>> time(millis=1338508800000) + SaneTime(1338508800000000,) + + >>> time(seconds=1338508800) + SaneTime(1338508800000000,) + + >>> time(minutes=22308480, tz='America/New_York') + SaneTime(1338508800000000,) + + +If you have the calendar parameters, then construct just as you would a datetime: + + >>> time(2012,1,1) + SaneTime(1325376000000000,) + + >>> time(2012,1,1,12,30,1) + SaneTime(1325421001000000,) + + >>> time(2012,1,1,12,30,1,1, tz='America/New_York') + SaneTime(1325421001000001,) + + +If you already have a datetime object, just construct from that: + + >>> dt = datetime(2012,1,1) + >>> time(dt) + SaneTime(1325376000000000,) + + +Or construct from a parsable string: + + >>> time('January 1st, 2012 12:30:01pm') + SaneTime(1325421001000000,) + + >>> time('January 1st, 2012 12:30:01pm', tz='America/New_York') + SaneTime(1325421001000000,) + + +####arithmetic + +Adding any int/long assumes it to be in microseconds. You can also add any :ref:`delta`: + + >>> time(2012,1,1) + 5 + SaneTime(1325376000000005,) + + >>> time(2012,1,1) + delta(hours=5) + SaneTime(1325394000000000,) + + +Subtracting two sanetimes produces a :ref:`delta`: + + >>> time() - time(2012,1,1) # time since new year + SaneDelta(15131339063956) + + >>> abs(time() - time()).micros # microseconds to construct a time + 30 + + +####conversion + +You can easily convert to a timezone-aware datetime or to a naive datetime. They are accessed as properties. + + >>> time(2012,1,1,tz='America/Los_Angeles').datetime + datetime.datetime(2012, 1, 1, 0, 0, tzinfo=) + + >>> time(2012,1,1,tz='America/Los_Angeles').naive_datetime + datetime.datetime(2012, 1, 1, 0, 0) + + +There are other convenience datetime timezone conversions as well. + + >>> time(2012,1,1,tz='America/Los_Angeles').utc_datetime + datetime.datetime(2012, 1, 1, 8, 0, tzinfo=) + + >>> time(2012,1,1,tz='America/Los_Angeles').utc_naive_datetime + datetime.datetime(2012, 1, 1, 8, 0) + + >>> time(2012,1,1,tz='America/Los_Angeles').ny_datetime + datetime.datetime(2012, 1, 1, 3, 0, tzinfo=) + + >>> time(2012,1,1,tz='America/Los_Angeles').ny_naive_datetime + datetime.datetime(2012, 1, 1, 3, 0) + + +To epoch times: + + >>> time(2012,1,1).minutes + 22089600 + + >>> time(2012,1,1).seconds + 1325376000 + + >>> time(2012,1,1).millis + 1325376000000 + + >>> time(2012,1,1).micros + 1325376000000000 + + +long and int conversion just bring back the epoch microseconds + + >>> int(time(2012,1,1)) + 1325376000000000 + + >>> long(time(2012,1,1)) + 1325376000000000L + + +#####date/time parts + +You can get at any of the date parts just as you might with datetime properties. Be careful-- these properties are all singular. Do not confuse with the plural epoch possiblities of the previous section. (this ambiguity will be fixed in future versions) + + >>> time().year + 2012 + >>> time().month + 6 + >>> time().day + 24 + >>> time().hour + 3 + >>> time().minute + 42 + >>> time().second + 12 + >>> time().micro + 664819 + + +###tztime +The `tztime` class is exactly like the `time` object, except that timezone **does** factor into equality. +A moment in `tztime` experienced in America/New\_York is **not** the same as the same `tztime` moment experienced in Europe/Dublin. + +###delta +The `delta` class represents a period of time, and provides easy access to all the different ways you might slice and dice this: micros, millis, seconds, minutes, hours, mean\_days, mean\_weeks, mean\_months, mean\_years. +There are also many different flavors of these: rounded, floored, floated, positional, rounded\_positional. +There is no attempt made in delta yet to be calendar aware (hence the 'mean' prefixes in some cases). + +###span +The `span` class represents a window of time ranging from one specific moment in time to another specific moment in time. +You can think of it as a start `time` with a `delta`, or as a start `time` and a stop `time`. + +###django +A django model field is also provided: `SaneTimeField`, that makes it super simple to store a sanetime. +They honor the auto\_add and auto\_add\_now features to easily turn your sanetimes into updated\_at or created\_at fields. +And they even work with south out of the box. + + +###NOTE +This documentation is still a work in progress. +Lots of good docs are now in place here, but there are still features lying in the code waiting documentation. +As always, the code should be treated as the ultimate source of truth. +If you haven't found what you're looking for you, you may very well find it implemented in the code. +Please feel free to help us bring it to the surface in the docs. + + + +###design principles +* simple: simplify usecases to single method/property +* intuitive: easy to remember methods/properties, with guessable aliases - be as verbose (and communicative) or as terse (and efficient) as you want to be. for example t = time(); t.ms == t.millis == t.milliseconds +* properties whenever sensible: properties are especially useful for django, cuz you can use them directly in templates without having to stage them first in the views. + + +###FAQ +Why is everything stored internally as microseconds? + +Python's datetime gives us access to microseconds, and since milliseconds would already have us cross the 32bit integer boundary, we might as well capture everything we can and take on microseconds as well. +There are plenty of helpers on the time, tztime, and delta that make using epoch seconds or milis just as easy as using micros. + + + diff --git a/README.rst b/README.rst deleted file mode 100644 index 3c3e1bf..0000000 --- a/README.rst +++ /dev/null @@ -1,9 +0,0 @@ -sanetime -======== - -**A sane date/time python interface** - -better epoch time, timezones, and deltas, django support as well - -docs: http://hubspot.github.com/sanetime/ - diff --git a/docs/.gitignore b/docs/.gitignore deleted file mode 100644 index e35d885..0000000 --- a/docs/.gitignore +++ /dev/null @@ -1 +0,0 @@ -_build diff --git a/docs/Makefile b/docs/Makefile deleted file mode 100644 index 4e6516c..0000000 --- a/docs/Makefile +++ /dev/null @@ -1,155 +0,0 @@ -# Makefile for Sphinx documentation -# - -# You can set these variables from the command line. -SPHINXOPTS = -SPHINXBUILD = sphinx-build -#SPHINXBUILD = python /Users/prior/.virtualenvs/sanetime/bin/sphinx-build - -PAPER = -BUILDDIR = _build - -# Internal variables. -PAPEROPT_a4 = -D latex_paper_size=a4 -PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . -# the i18n builder cannot share the environment and doctrees with the others -I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . - -.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext - -help: - @echo "Please use \`make ' where is one of" - @echo " html to make standalone HTML files" - @echo " dirhtml to make HTML files named index.html in directories" - @echo " singlehtml to make a single large HTML file" - @echo " pickle to make pickle files" - @echo " json to make JSON files" - @echo " htmlhelp to make HTML files and a HTML help project" - @echo " qthelp to make HTML files and a qthelp project" - @echo " devhelp to make HTML files and a Devhelp project" - @echo " epub to make an epub" - @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" - @echo " latexpdf to make LaTeX files and run them through pdflatex" - @echo " text to make text files" - @echo " man to make manual pages" - @echo " texinfo to make Texinfo files" - @echo " info to make Texinfo files and run them through makeinfo" - @echo " gettext to make PO message catalogs" - @echo " changes to make an overview of all changed/added/deprecated items" - @echo " linkcheck to check all external links for integrity" - @echo " doctest to run all doctests embedded in the documentation (if enabled)" - -clean: - -rm -rf $(BUILDDIR)/* - -html: - $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." - -dirhtml: - $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." - -singlehtml: - $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml - @echo - @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." - -pickle: - $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle - @echo - @echo "Build finished; now you can process the pickle files." - -json: - $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json - @echo - @echo "Build finished; now you can process the JSON files." - -htmlhelp: - $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp - @echo - @echo "Build finished; now you can run HTML Help Workshop with the" \ - ".hhp project file in $(BUILDDIR)/htmlhelp." - -qthelp: - $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp - @echo - @echo "Build finished; now you can run "qcollectiongenerator" with the" \ - ".qhcp project file in $(BUILDDIR)/qthelp, like this:" - @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/sanetime.qhcp" - @echo "To view the help file:" - @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/sanetime.qhc" - -devhelp: - $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp - @echo - @echo "Build finished." - @echo "To view the help file:" - @echo "# mkdir -p $$HOME/.local/share/devhelp/sanetime" - @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/sanetime" - @echo "# devhelp" - -epub: - $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub - @echo - @echo "Build finished. The epub file is in $(BUILDDIR)/epub." - -latex: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo - @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." - @echo "Run \`make' in that directory to run these through (pdf)latex" \ - "(use \`make latexpdf' here to do that automatically)." - -latexpdf: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo "Running LaTeX files through pdflatex..." - $(MAKE) -C $(BUILDDIR)/latex all-pdf - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - -text: - $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text - @echo - @echo "Build finished. The text files are in $(BUILDDIR)/text." - -man: - $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man - @echo - @echo "Build finished. The manual pages are in $(BUILDDIR)/man." - -texinfo: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo - @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." - @echo "Run \`make' in that directory to run these through makeinfo" \ - "(use \`make info' here to do that automatically)." - -info: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo "Running Texinfo files through makeinfo..." - make -C $(BUILDDIR)/texinfo info - @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." - -gettext: - $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale - @echo - @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." - -changes: - $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes - @echo - @echo "The overview file is in $(BUILDDIR)/changes." - -linkcheck: - $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck - @echo - @echo "Link check complete; look for any errors in the above output " \ - "or in $(BUILDDIR)/linkcheck/output.txt." - -doctest: - $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest - @echo "Testing of doctests in the sources finished, look at the " \ - "results in $(BUILDDIR)/doctest/output.txt." diff --git a/docs/_static/requests-sidebar.png b/docs/_static/requests-sidebar.png deleted file mode 100644 index 88a8147..0000000 Binary files a/docs/_static/requests-sidebar.png and /dev/null differ diff --git a/docs/_templates/sidebarintro.html b/docs/_templates/sidebarintro.html deleted file mode 100644 index 1932de5..0000000 --- a/docs/_templates/sidebarintro.html +++ /dev/null @@ -1,24 +0,0 @@ -

sanetime

- -

- -

- -

- sanetime brings epoch sanity to dates and times in python. - You are currently looking at the documentation of the development release. -

- -

feedback

-

- Feedback is greatly appreciated. - Feel free to get in touch with us in github or create an issue as necessary. -

- -

useful links

- diff --git a/docs/_templates/sidebarlogo.html b/docs/_templates/sidebarlogo.html deleted file mode 100644 index ea8b12b..0000000 --- a/docs/_templates/sidebarlogo.html +++ /dev/null @@ -1,11 +0,0 @@ -

sanetime

-

- -

- -

- sanetime brings epoch sanity to dates and times in python. - You are currently looking at the documentation of the development release. -

- diff --git a/docs/_themes/.gitignore b/docs/_themes/.gitignore deleted file mode 100644 index 66b6e4c..0000000 --- a/docs/_themes/.gitignore +++ /dev/null @@ -1,3 +0,0 @@ -*.pyc -*.pyo -.DS_Store diff --git a/docs/_themes/LICENSE b/docs/_themes/LICENSE deleted file mode 100644 index 33ee17b..0000000 --- a/docs/_themes/LICENSE +++ /dev/null @@ -1,50 +0,0 @@ -Further Modifications: - -Copyright (c) 2012 HubSpot, Inc. - - -Modifications: - -Copyright (c) 2011 Kenneth Reitz. - - -Original Project: - -Copyright (c) 2010 by Armin Ronacher. - - -Some rights reserved. - -Redistribution and use in source and binary forms of the theme, with or -without modification, are permitted provided that the following conditions -are met: - -* Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - -* Redistributions in binary form must reproduce the above - copyright notice, this list of conditions and the following - disclaimer in the documentation and/or other materials provided - with the distribution. - -* The names of the contributors may not be used to endorse or - promote products derived from this software without specific - prior written permission. - -We kindly ask you to only use these themes in an unmodified manner just -for Flask and Flask-related products, not for unrelated projects. If you -like the visual style and want to use it for your own projects, please -consider making some larger changes to the themes (such as changing -font faces, sizes, colors or margins). - -THIS THEME IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" -AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE -LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR -CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF -SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS -INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN -CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) -ARISING IN ANY WAY OUT OF THE USE OF THIS THEME, EVEN IF ADVISED OF THE -POSSIBILITY OF SUCH DAMAGE. diff --git a/docs/_themes/README.rst b/docs/_themes/README.rst deleted file mode 100644 index 6b41917..0000000 --- a/docs/_themes/README.rst +++ /dev/null @@ -1,25 +0,0 @@ -krTheme Sphinx Style -==================== - -This repository contains sphinx styles lifted from Kenneth Reitz's -requests library. It is a derivative of Mitsuhiko's themes for Flask -and Flask related projects. To use this style in your Sphinx -documentation, follow this guide: - -1. put this folder as _themes into your docs folder. Alternatively - you can also use git submodules to check out the contents there. - -2. add this to your conf.py: :: - - sys.path.append(os.path.abspath('_themes')) - html_theme_path = ['_themes'] - html_theme = 'flask' - -The following themes exist: - -**kr** - the standard flask documentation theme for large projects - -**kr_small** - small one-page theme. Intended to be used by very small addon libraries. - diff --git a/docs/_themes/flask_theme_support.py b/docs/_themes/flask_theme_support.py deleted file mode 100644 index 33f4744..0000000 --- a/docs/_themes/flask_theme_support.py +++ /dev/null @@ -1,86 +0,0 @@ -# flasky extensions. flasky pygments style based on tango style -from pygments.style import Style -from pygments.token import Keyword, Name, Comment, String, Error, \ - Number, Operator, Generic, Whitespace, Punctuation, Other, Literal - - -class FlaskyStyle(Style): - background_color = "#f8f8f8" - default_style = "" - - styles = { - # No corresponding class for the following: - #Text: "", # class: '' - Whitespace: "underline #f8f8f8", # class: 'w' - Error: "#a40000 border:#ef2929", # class: 'err' - Other: "#000000", # class 'x' - - Comment: "italic #8f5902", # class: 'c' - Comment.Preproc: "noitalic", # class: 'cp' - - Keyword: "bold #004461", # class: 'k' - Keyword.Constant: "bold #004461", # class: 'kc' - Keyword.Declaration: "bold #004461", # class: 'kd' - Keyword.Namespace: "bold #004461", # class: 'kn' - Keyword.Pseudo: "bold #004461", # class: 'kp' - Keyword.Reserved: "bold #004461", # class: 'kr' - Keyword.Type: "bold #004461", # class: 'kt' - - Operator: "#582800", # class: 'o' - Operator.Word: "bold #004461", # class: 'ow' - like keywords - - Punctuation: "bold #000000", # class: 'p' - - # because special names such as Name.Class, Name.Function, etc. - # are not recognized as such later in the parsing, we choose them - # to look the same as ordinary variables. - Name: "#000000", # class: 'n' - Name.Attribute: "#c4a000", # class: 'na' - to be revised - Name.Builtin: "#004461", # class: 'nb' - Name.Builtin.Pseudo: "#3465a4", # class: 'bp' - Name.Class: "#000000", # class: 'nc' - to be revised - Name.Constant: "#000000", # class: 'no' - to be revised - Name.Decorator: "#888", # class: 'nd' - to be revised - Name.Entity: "#ce5c00", # class: 'ni' - Name.Exception: "bold #cc0000", # class: 'ne' - Name.Function: "#000000", # class: 'nf' - Name.Property: "#000000", # class: 'py' - Name.Label: "#f57900", # class: 'nl' - Name.Namespace: "#000000", # class: 'nn' - to be revised - Name.Other: "#000000", # class: 'nx' - Name.Tag: "bold #004461", # class: 'nt' - like a keyword - Name.Variable: "#000000", # class: 'nv' - to be revised - Name.Variable.Class: "#000000", # class: 'vc' - to be revised - Name.Variable.Global: "#000000", # class: 'vg' - to be revised - Name.Variable.Instance: "#000000", # class: 'vi' - to be revised - - Number: "#990000", # class: 'm' - - Literal: "#000000", # class: 'l' - Literal.Date: "#000000", # class: 'ld' - - String: "#4e9a06", # class: 's' - String.Backtick: "#4e9a06", # class: 'sb' - String.Char: "#4e9a06", # class: 'sc' - String.Doc: "italic #8f5902", # class: 'sd' - like a comment - String.Double: "#4e9a06", # class: 's2' - String.Escape: "#4e9a06", # class: 'se' - String.Heredoc: "#4e9a06", # class: 'sh' - String.Interpol: "#4e9a06", # class: 'si' - String.Other: "#4e9a06", # class: 'sx' - String.Regex: "#4e9a06", # class: 'sr' - String.Single: "#4e9a06", # class: 's1' - String.Symbol: "#4e9a06", # class: 'ss' - - Generic: "#000000", # class: 'g' - Generic.Deleted: "#a40000", # class: 'gd' - Generic.Emph: "italic #000000", # class: 'ge' - Generic.Error: "#ef2929", # class: 'gr' - Generic.Heading: "bold #000080", # class: 'gh' - Generic.Inserted: "#00A000", # class: 'gi' - Generic.Output: "#888", # class: 'go' - Generic.Prompt: "#745334", # class: 'gp' - Generic.Strong: "bold #000000", # class: 'gs' - Generic.Subheading: "bold #800080", # class: 'gu' - Generic.Traceback: "bold #a40000", # class: 'gt' - } diff --git a/docs/_themes/kr/layout.html b/docs/_themes/kr/layout.html deleted file mode 100644 index 9079f84..0000000 --- a/docs/_themes/kr/layout.html +++ /dev/null @@ -1,18 +0,0 @@ -{%- extends "basic/layout.html" %} -{%- block extrahead %} - {{ super() }} - {% if theme_touch_icon %} - - {% endif %} - -{% endblock %} -{%- block relbar2 %}{% endblock %} -{%- block footer %} -
- © Copyright {{ copyright }}. -
- - Fork me on GitHub - - -{%- endblock %} diff --git a/docs/_themes/kr/relations.html b/docs/_themes/kr/relations.html deleted file mode 100644 index 3bbcde8..0000000 --- a/docs/_themes/kr/relations.html +++ /dev/null @@ -1,19 +0,0 @@ -

Related Topics

- diff --git a/docs/_themes/kr/static/flasky.css_t b/docs/_themes/kr/static/flasky.css_t deleted file mode 100644 index 3a13c35..0000000 --- a/docs/_themes/kr/static/flasky.css_t +++ /dev/null @@ -1,536 +0,0 @@ -/* - * flasky.css_t - * ~~~~~~~~~~~~ - * - * :copyright: Copyright 2010 by Armin Ronacher. Modifications by Kenneth Reitz. - * :license: Flask Design License, see LICENSE for details. - */ - -{% set page_width = '940px' %} -{% set sidebar_width = '220px' %} - -@import url("basic.css"); - -/* -- page layout ----------------------------------------------------------- */ - -body { - font-family: 'goudy old style', 'minion pro', 'bell mt', Georgia, 'Hiragino Mincho Pro'; - font-size: 17px; - background-color: white; - color: #000; - margin: 0; - padding: 0; -} - -div.document { - width: {{ page_width }}; - margin: 30px auto 0 auto; -} - -div.documentwrapper { - float: left; - width: 100%; -} - -div.bodywrapper { - margin: 0 0 0 {{ sidebar_width }}; -} - -div.sphinxsidebar { - width: {{ sidebar_width }}; -} - -hr { - border: 1px solid #B1B4B6; -} - -div.body { - background-color: #ffffff; - color: #3E4349; - padding: 0 30px 0 30px; -} - -img.floatingflask { - padding: 0 0 10px 10px; - float: right; -} - -div.footer { - width: {{ page_width }}; - margin: 20px auto 30px auto; - font-size: 14px; - color: #888; - text-align: right; -} - -div.footer a { - color: #888; -} - -div.related { - display: none; -} - -div.sphinxsidebar a { - color: #444; - text-decoration: none; - border-bottom: 1px dotted #999; -} - -div.sphinxsidebar a:hover { - border-bottom: 1px solid #999; -} - -div.sphinxsidebar { - font-size: 14px; - line-height: 1.5; -} - -div.sphinxsidebarwrapper { - padding: 18px 10px; -} - -div.sphinxsidebarwrapper p.logo { - padding: 0; - margin: -10px 0 0 -20px; - text-align: center; -} - -div.sphinxsidebar h3, -div.sphinxsidebar h4 { - font-family: 'Garamond', 'Georgia', serif; - color: #444; - font-size: 24px; - font-weight: normal; - margin: 0 0 5px 0; - padding: 0; -} - -div.sphinxsidebar h4 { - font-size: 20px; -} - -div.sphinxsidebar h3 a { - color: #444; -} - -div.sphinxsidebar p.logo a, -div.sphinxsidebar h3 a, -div.sphinxsidebar p.logo a:hover, -div.sphinxsidebar h3 a:hover { - border: none; -} - -div.sphinxsidebar p { - color: #555; - margin: 10px 0; -} - -div.sphinxsidebar ul { - margin: 10px 0; - padding: 0; - color: #000; -} - -div.sphinxsidebar input { - border: 1px solid #ccc; - font-family: 'Georgia', serif; - font-size: 1em; -} - -/* -- body styles ----------------------------------------------------------- */ - -a { - color: #004B6B; - text-decoration: underline; -} - -a:hover { - color: #6D4100; - text-decoration: underline; -} - -div.body h1, -div.body h2, -div.body h3, -div.body h4, -div.body h5, -div.body h6 { - font-family: 'Garamond', 'Georgia', serif; - font-weight: normal; - margin: 30px 0px 10px 0px; - padding: 0; -} - -div.body h1 { margin-top: 0; padding-top: 0; font-size: 240%; } -div.body h2 { font-size: 180%; } -div.body h3 { font-size: 150%; } -div.body h4 { font-size: 130%; } -div.body h5 { font-size: 100%; } -div.body h6 { font-size: 100%; } - -a.headerlink { - color: #ddd; - padding: 0 4px; - text-decoration: none; -} - -a.headerlink:hover { - color: #444; - background: #eaeaea; -} - -div.body p, div.body dd, div.body li { - line-height: 1.4em; -} - -div.admonition { - background: #fafafa; - margin: 20px -30px; - padding: 10px 30px; - border-top: 1px solid #ccc; - border-bottom: 1px solid #ccc; -} - -div.admonition tt.xref, div.admonition a tt { - border-bottom: 1px solid #fafafa; -} - -dd div.admonition { - margin-left: -60px; - padding-left: 60px; -} - -div.admonition p.admonition-title { - font-family: 'Garamond', 'Georgia', serif; - font-weight: normal; - font-size: 24px; - margin: 0 0 10px 0; - padding: 0; - line-height: 1; -} - -div.admonition p.last { - margin-bottom: 0; -} - -div.highlight { - background-color: white; -} - -dt:target, .highlight { - background: #FAF3E8; -} - -div.note { - background-color: #eee; - border: 1px solid #ccc; -} - -div.seealso { - background-color: #ffc; - border: 1px solid #ff6; -} - -div.topic { - background-color: #eee; -} - -p.admonition-title { - display: inline; -} - -p.admonition-title:after { - content: ":"; -} - -pre, tt { - font-family: 'Consolas', 'Menlo', 'Deja Vu Sans Mono', 'Bitstream Vera Sans Mono', monospace; - font-size: 0.9em; -} - -img.screenshot { -} - -tt.descname, tt.descclassname { - font-size: 0.95em; -} - -tt.descname { - padding-right: 0.08em; -} - -img.screenshot { - -moz-box-shadow: 2px 2px 4px #eee; - -webkit-box-shadow: 2px 2px 4px #eee; - box-shadow: 2px 2px 4px #eee; -} - -table.docutils { - border: 1px solid #888; - -moz-box-shadow: 2px 2px 4px #eee; - -webkit-box-shadow: 2px 2px 4px #eee; - box-shadow: 2px 2px 4px #eee; -} - -table.docutils td, table.docutils th { - border: 1px solid #888; - padding: 0.25em 0.7em; -} - -table.field-list, table.footnote { - border: none; - -moz-box-shadow: none; - -webkit-box-shadow: none; - box-shadow: none; -} - -table.footnote { - margin: 15px 0; - width: 100%; - border: 1px solid #eee; - background: #fdfdfd; - font-size: 0.9em; -} - -table.footnote + table.footnote { - margin-top: -15px; - border-top: none; -} - -table.field-list th { - padding: 0 0.8em 0 0; -} - -table.field-list td { - padding: 0; -} - -table.footnote td.label { - width: 0px; - padding: 0.3em 0 0.3em 0.5em; -} - -table.footnote td { - padding: 0.3em 0.5em; -} - -dl { - margin: 0; - padding: 0; -} - -dl dd { - margin-left: 30px; -} - -blockquote { - margin: 0 0 0 30px; - padding: 0; -} - -ul, ol { - margin: 10px 0 10px 30px; - padding: 0; -} - -pre { - background: #eee; - padding: 7px 30px; - margin: 15px -30px; - line-height: 1.3em; -} - -dl pre, blockquote pre, li pre { - margin-left: -60px; - padding-left: 60px; -} - -dl dl pre { - margin-left: -90px; - padding-left: 90px; -} - -tt { - background-color: #ecf0f3; - color: #222; - /* padding: 1px 2px; */ -} - -tt.xref, a tt { - background-color: #FBFBFB; - border-bottom: 1px solid white; -} - -a.reference { - text-decoration: none; - border-bottom: 1px dotted #004B6B; -} - -a.reference:hover { - border-bottom: 1px solid #6D4100; -} - -a.footnote-reference { - text-decoration: none; - font-size: 0.7em; - vertical-align: top; - border-bottom: 1px dotted #004B6B; -} - -a.footnote-reference:hover { - border-bottom: 1px solid #6D4100; -} - -a:hover tt { - background: #EEE; -} - - -@media screen and (max-width: 870px) { - - div.sphinxsidebar { - display: none; - } - - div.document { - width: 100%; - - } - - div.documentwrapper { - margin-left: 0; - margin-top: 0; - margin-right: 0; - margin-bottom: 0; - } - - div.bodywrapper { - margin-top: 0; - margin-right: 0; - margin-bottom: 0; - margin-left: 0; - } - - ul { - margin-left: 0; - } - - .document { - width: auto; - } - - .footer { - width: auto; - } - - .bodywrapper { - margin: 0; - } - - .footer { - width: auto; - } - - .github { - display: none; - } - - - -} - - - -@media screen and (max-width: 875px) { - - body { - margin: 0; - padding: 20px 30px; - } - - div.documentwrapper { - float: none; - background: white; - } - - div.sphinxsidebar { - display: block; - float: none; - width: 102.5%; - margin: 50px -30px -20px -30px; - padding: 10px 20px; - background: #333; - color: white; - } - - div.sphinxsidebar h3, div.sphinxsidebar h4, div.sphinxsidebar p, - div.sphinxsidebar h3 a { - color: white; - } - - div.sphinxsidebar a { - color: #aaa; - } - - div.sphinxsidebar p.logo { - display: none; - } - - div.document { - width: 100%; - margin: 0; - } - - div.related { - display: block; - margin: 0; - padding: 10px 0 20px 0; - } - - div.related ul, - div.related ul li { - margin: 0; - padding: 0; - } - - div.footer { - display: none; - } - - div.bodywrapper { - margin: 0; - } - - div.body { - min-height: 0; - padding: 0; - } - - .rtd_doc_footer { - display: none; - } - - .document { - width: auto; - } - - .footer { - width: auto; - } - - .footer { - width: auto; - } - - .github { - display: none; - } -} - - -/* misc. */ - -.revsys-inline { - display: none!important; -} \ No newline at end of file diff --git a/docs/_themes/kr/theme.conf b/docs/_themes/kr/theme.conf deleted file mode 100644 index 307a1f0..0000000 --- a/docs/_themes/kr/theme.conf +++ /dev/null @@ -1,7 +0,0 @@ -[theme] -inherit = basic -stylesheet = flasky.css -pygments_style = flask_theme_support.FlaskyStyle - -[options] -touch_icon = diff --git a/docs/_themes/kr_small/layout.html b/docs/_themes/kr_small/layout.html deleted file mode 100644 index aa1716a..0000000 --- a/docs/_themes/kr_small/layout.html +++ /dev/null @@ -1,22 +0,0 @@ -{% extends "basic/layout.html" %} -{% block header %} - {{ super() }} - {% if pagename == 'index' %} -
- {% endif %} -{% endblock %} -{% block footer %} - {% if pagename == 'index' %} -
- {% endif %} -{% endblock %} -{# do not display relbars #} -{% block relbar1 %}{% endblock %} -{% block relbar2 %} - {% if theme_github_fork %} - Fork me on GitHub - {% endif %} -{% endblock %} -{% block sidebar1 %}{% endblock %} -{% block sidebar2 %}{% endblock %} diff --git a/docs/_themes/kr_small/static/flasky.css_t b/docs/_themes/kr_small/static/flasky.css_t deleted file mode 100644 index fe2141c..0000000 --- a/docs/_themes/kr_small/static/flasky.css_t +++ /dev/null @@ -1,287 +0,0 @@ -/* - * flasky.css_t - * ~~~~~~~~~~~~ - * - * Sphinx stylesheet -- flasky theme based on nature theme. - * - * :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS. - * :license: BSD, see LICENSE for details. - * - */ - -@import url("basic.css"); - -/* -- page layout ----------------------------------------------------------- */ - -body { - font-family: 'Georgia', serif; - font-size: 17px; - color: #000; - background: white; - margin: 0; - padding: 0; -} - -div.documentwrapper { - float: left; - width: 100%; -} - -div.bodywrapper { - margin: 40px auto 0 auto; - width: 700px; -} - -hr { - border: 1px solid #B1B4B6; -} - -div.body { - background-color: #ffffff; - color: #3E4349; - padding: 0 30px 30px 30px; -} - -img.floatingflask { - padding: 0 0 10px 10px; - float: right; -} - -div.footer { - text-align: right; - color: #888; - padding: 10px; - font-size: 14px; - width: 650px; - margin: 0 auto 40px auto; -} - -div.footer a { - color: #888; - text-decoration: underline; -} - -div.related { - line-height: 32px; - color: #888; -} - -div.related ul { - padding: 0 0 0 10px; -} - -div.related a { - color: #444; -} - -/* -- body styles ----------------------------------------------------------- */ - -a { - color: #004B6B; - text-decoration: underline; -} - -a:hover { - color: #6D4100; - text-decoration: underline; -} - -div.body { - padding-bottom: 40px; /* saved for footer */ -} - -div.body h1, -div.body h2, -div.body h3, -div.body h4, -div.body h5, -div.body h6 { - font-family: 'Garamond', 'Georgia', serif; - font-weight: normal; - margin: 30px 0px 10px 0px; - padding: 0; -} - -{% if theme_index_logo %} -div.indexwrapper h1 { - text-indent: -999999px; - background: url({{ theme_index_logo }}) no-repeat center center; - height: {{ theme_index_logo_height }}; -} -{% endif %} - -div.body h2 { font-size: 180%; } -div.body h3 { font-size: 150%; } -div.body h4 { font-size: 130%; } -div.body h5 { font-size: 100%; } -div.body h6 { font-size: 100%; } - -a.headerlink { - color: white; - padding: 0 4px; - text-decoration: none; -} - -a.headerlink:hover { - color: #444; - background: #eaeaea; -} - -div.body p, div.body dd, div.body li { - line-height: 1.4em; -} - -div.admonition { - background: #fafafa; - margin: 20px -30px; - padding: 10px 30px; - border-top: 1px solid #ccc; - border-bottom: 1px solid #ccc; -} - -div.admonition p.admonition-title { - font-family: 'Garamond', 'Georgia', serif; - font-weight: normal; - font-size: 24px; - margin: 0 0 10px 0; - padding: 0; - line-height: 1; -} - -div.admonition p.last { - margin-bottom: 0; -} - -div.highlight{ - background-color: white; -} - -dt:target, .highlight { - background: #FAF3E8; -} - -div.note { - background-color: #eee; - border: 1px solid #ccc; -} - -div.seealso { - background-color: #ffc; - border: 1px solid #ff6; -} - -div.topic { - background-color: #eee; -} - -div.warning { - background-color: #ffe4e4; - border: 1px solid #f66; -} - -p.admonition-title { - display: inline; -} - -p.admonition-title:after { - content: ":"; -} - -pre, tt { - font-family: 'Consolas', 'Menlo', 'Deja Vu Sans Mono', 'Bitstream Vera Sans Mono', monospace; - font-size: 0.85em; -} - -img.screenshot { -} - -tt.descname, tt.descclassname { - font-size: 0.95em; -} - -tt.descname { - padding-right: 0.08em; -} - -img.screenshot { - -moz-box-shadow: 2px 2px 4px #eee; - -webkit-box-shadow: 2px 2px 4px #eee; - box-shadow: 2px 2px 4px #eee; -} - -table.docutils { - border: 1px solid #888; - -moz-box-shadow: 2px 2px 4px #eee; - -webkit-box-shadow: 2px 2px 4px #eee; - box-shadow: 2px 2px 4px #eee; -} - -table.docutils td, table.docutils th { - border: 1px solid #888; - padding: 0.25em 0.7em; -} - -table.field-list, table.footnote { - border: none; - -moz-box-shadow: none; - -webkit-box-shadow: none; - box-shadow: none; -} - -table.footnote { - margin: 15px 0; - width: 100%; - border: 1px solid #eee; -} - -table.field-list th { - padding: 0 0.8em 0 0; -} - -table.field-list td { - padding: 0; -} - -table.footnote td { - padding: 0.5em; -} - -dl { - margin: 0; - padding: 0; -} - -dl dd { - margin-left: 30px; -} - -pre { - padding: 0; - margin: 15px -30px; - padding: 8px; - line-height: 1.3em; - padding: 7px 30px; - background: #eee; - border-radius: 2px; - -moz-border-radius: 2px; - -webkit-border-radius: 2px; -} - -dl pre { - margin-left: -60px; - padding-left: 60px; -} - -tt { - background-color: #ecf0f3; - color: #222; - /* padding: 1px 2px; */ -} - -tt.xref, a tt { - background-color: #FBFBFB; -} - -a:hover tt { - background: #EEE; -} diff --git a/docs/_themes/kr_small/theme.conf b/docs/_themes/kr_small/theme.conf deleted file mode 100644 index 542b462..0000000 --- a/docs/_themes/kr_small/theme.conf +++ /dev/null @@ -1,10 +0,0 @@ -[theme] -inherit = basic -stylesheet = flasky.css -nosidebar = true -pygments_style = flask_theme_support.FlaskyStyle - -[options] -index_logo = '' -index_logo_height = 120px -github_fork = '' diff --git a/docs/api.rst b/docs/api.rst deleted file mode 100644 index 499ffd3..0000000 --- a/docs/api.rst +++ /dev/null @@ -1,144 +0,0 @@ -.. _api: - -API -=== - -.. module:: requests - -This part of the documentation covers all the interfaces of Requests. For -parts where Requests depends on external libraries, we document the most -important right here and provide links to the canonical documentation. - - -Main Interface --------------- - -All of Request's functionality can be accessed by these 7 methods. -They all return an instance of the :class:`Response ` object. - -.. autofunction:: request - ---------------------- - - -.. autoclass:: Response - :inherited-members: - ---------------------- - -.. autofunction:: head -.. autofunction:: get -.. autofunction:: post -.. autofunction:: put -.. autofunction:: patch -.. autofunction:: delete - - ------------------ - -.. autofunction:: session - - - -Exceptions -~~~~~~~~~~ - -.. module:: requests - -.. autoexception:: RequestException -.. autoexception:: ConnectionError -.. autoexception:: HTTPError -.. autoexception:: URLRequired -.. autoexception:: TooManyRedirects - - -.. _configurations: - -Configurations --------------- - -.. automodule:: requests.defaults - - -.. _async: - -Async ------ - -.. module:: requests.async - - -.. autofunction:: map -.. autofunction:: request -.. autofunction:: head -.. autofunction:: get -.. autofunction:: post -.. autofunction:: put -.. autofunction:: patch -.. autofunction:: delete - - - -Utilities ---------- - -These functions are used internally, but may be useful outside of -Requests. - -.. module:: requests.utils - -Status Code Lookup -~~~~~~~~~~~~~~~~~~ - -.. autofunction:: requests.codes - -:: - - >>> requests.codes['temporary_redirect'] - 307 - - >>> requests.codes.teapot - 418 - - >>> requests.codes['\o/'] - 200 - -Cookies -~~~~~~~ - -.. autofunction:: dict_from_cookiejar -.. autofunction:: cookiejar_from_dict -.. autofunction:: add_dict_to_cookiejar - - -Encodings -~~~~~~~~~ - -.. autofunction:: get_encodings_from_content -.. autofunction:: get_encoding_from_headers -.. autofunction:: get_unicode_from_response -.. autofunction:: decode_gzip - - -Internals ---------- - -These items are an internal component to Requests, and should never be -seen by the end user (developer). This part of the API documentation -exists for those who are extending the functionality of Requests. - - -Classes -~~~~~~~ - -.. autoclass:: requests.Response - :inherited-members: - -.. autoclass:: requests.Request - :inherited-members: - -.. _sessionapi: - -.. autoclass:: requests.Session - :inherited-members: - diff --git a/docs/blah.rst b/docs/blah.rst deleted file mode 100644 index b6e61d6..0000000 --- a/docs/blah.rst +++ /dev/null @@ -1,2 +0,0 @@ -test -==== diff --git a/docs/community/faq.rst b/docs/community/faq.rst deleted file mode 100644 index fa9b068..0000000 --- a/docs/community/faq.rst +++ /dev/null @@ -1,83 +0,0 @@ -.. _faq: - -Frequently Asked Questions -========================== - -This part of the documentation answers common questions about Requests. - -Encoded Data? -------------- - -Requests automatically decompresses gzip-encoded responses, and does -its best to decode response content to unicode when possible. - -You can get direct access to the raw response (and even the socket), -if needed as well. - - -Custom User-Agents? -------------------- - -Requests allows you to easily override User-Agent strings, along with -any other HTTP Header. - - -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? ------------------ - -Yes! Here's a list of Python platforms that are officially -supported: - -* cPython 2.6 -* cPython 2.7 -* cPython 3.1 -* cPython 3.2 -* PyPy-c 1.4 -* PyPy-c 1.5 -* PyPy-c 1.6 -* PyPy-c 1.7 - - -Keep-alive Support? -------------------- - -Yep! - - -Proxy Support? --------------- - -You bet! - - -SSL Verification? ------------------ - -Absolutely. - diff --git a/docs/community/out-there.rst b/docs/community/out-there.rst deleted file mode 100644 index 9b90771..0000000 --- a/docs/community/out-there.rst +++ /dev/null @@ -1,64 +0,0 @@ -Modules -======= - -- `requests-oauth `_, adds OAuth support to Requests. -- `rauth `_, an alternative to requests-oauth, supports OAuth versions 1.0 and 2.0. -- `FacePy `_, a Python wrapper to the Facebook API. -- `robotframework-requests `_, a Robot Framework API wrapper. -- `fullerene `_, a Graphite Dashboard. -- `urbanairship-python `_, a fork of the Urban Airship API wrapper. -- `WhitespaceBot `_, a project that automatically forks repos, strips trailing whitespace, and sends a pull request. -- `python-rexster `_, Rexter client that provides a simple interface for graph databases. -- `daikon `_, a CLI for ElasticSearch. - -Articles & Talks -================ -- `Python for the Web `_ teaches how to use Python to interact with the web, using Requests. -- `Daniel Greenfield's Review of Requests `_ -- `My 'Python for Humans' talk `_ ( `audio `_ ) -- `Issac Kelly's 'Consuming Web APIs' talk `_ -- `Blog post about Requests via Yum `_ -- `Russian blog post introducing Requests `_ -- `French blog post introducing Requests `_ - - -Integrations -============ - -ScraperWiki ------------- - -`ScraperWiki `_ is an excellent service that allows -you to run Python, Ruby, and PHP scraper scripts on the web. Now, Requests -v0.6.1 is available to use in your scrapers! - -To give it a try, simply:: - - import requests - - -Managed Packages -================ - -Requests is available in a number of popular package formats. Of course, -the ideal way to install Requests is via The Cheeseshop. - - -Ubuntu & Debian ---------------- - -Requests is available installed as a Debian package! Debian Etch Ubuntu, since Oneiric:: - - $ apt-get install python-requests - - -Fedora and RedHat ------------------ - -You can easily install Requests v0.6.1 with yum on rpm-based systems:: - - $ yum install python-requests - - - - diff --git a/docs/community/support.rst b/docs/community/support.rst deleted file mode 100644 index 2dc0b31..0000000 --- a/docs/community/support.rst +++ /dev/null @@ -1,37 +0,0 @@ -.. _support: - -Support -======= - -If you have a questions or issues about Requests, there are several 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 deleted file mode 100644 index fe2f9bf..0000000 --- a/docs/community/updates.rst +++ /dev/null @@ -1,30 +0,0 @@ -.. _updates: - -Updates -======= - -If you'd like to stay up to date on the community and development of Requests, -there are several 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/conf.py b/docs/conf.py deleted file mode 100644 index 5424a1f..0000000 --- a/docs/conf.py +++ /dev/null @@ -1,243 +0,0 @@ -# -*- coding: utf-8 -*- -# -# Requests documentation build configuration file, created by -# sphinx-quickstart on Sun Feb 13 23:54:25 2011. -# -# This file is execfile()d with the current directory set to its containing dir. -# -# Note that not all possible configuration values are present in this -# autogenerated file. -# -# All configuration values have a default; values that are commented out -# serve to show the default. - -import sys, os - -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -sys.path.insert(0, os.path.abspath('..')) -from sanetime import __version__ - -# -- General configuration ----------------------------------------------------- - -# If your documentation needs a minimal Sphinx version, state it here. -#needs_sphinx = '1.0' - -# Add any Sphinx extension module names here, as strings. They can be extensions -# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = ['sphinx.ext.autodoc'] - -# Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] - -# The suffix of source filenames. -source_suffix = '.rst' - -# The encoding of source files. -#source_encoding = 'utf-8-sig' - -# The master toctree document. -master_doc = 'index' - -# General information about the project. -project = u'sanetime' -copyright = u'2012. A HubSpot Project' - -# The version info for the project you're documenting, acts as replacement for -# |version| and |release|, also used in various other places throughout the -# built documents. -# -# The short X.Y version. -version = __version__ -# The full version, including alpha/beta/rc tags. -release = version - -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. -#language = None - -# There are two options for replacing |today|: either, you set today to some -# non-false value, then it is used: -#today = '' -# Else, today_fmt is used as the format for a strftime call. -#today_fmt = '%B %d, %Y' - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -exclude_patterns = ['_build'] - -# The reST default role (used for this markup: `text`) to use for all documents. -#default_role = None - -# If true, '()' will be appended to :func: etc. cross-reference text. -#add_function_parentheses = True - -# If true, the current module name will be prepended to all description -# unit titles (such as .. function::). -#add_module_names = True - -# If true, sectionauthor and moduleauthor directives will be shown in the -# output. They are ignored by default. -#show_authors = False - -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'flask_theme_support.FlaskyStyle' - -# A list of ignored prefixes for module index sorting. -#modindex_common_prefix = [] - - -# -- Options for HTML output --------------------------------------------------- - -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -html_theme = 'default' - -# Theme options are theme-specific and customize the look and feel of a theme -# further. For a list of options available for each theme, see the -# documentation. -#html_theme_options = {} - -# Add any paths that contain custom themes here, relative to this directory. -#html_theme_path = [] - -# The name for this set of Sphinx documents. If None, it defaults to -# " v documentation". -#html_title = None - -# A shorter title for the navigation bar. Default is the same as html_title. -#html_short_title = None - -# The name of an image file (relative to this directory) to place at the top -# of the sidebar. -#html_logo = None - - -# The name of an image file (within the static path) to use as favicon of the -# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 -# pixels large. -#html_favicon = None - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] - -# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, -# using the given strftime format. -#html_last_updated_fmt = '%b %d, %Y' - -# If true, SmartyPants will be used to convert quotes and dashes to -# typographically correct entities. -#html_use_smartypants = True - -# Custom sidebar templates, maps document names to template names. -# Custom sidebar templates, maps document names to template names. -html_sidebars = { - 'index': ['sidebarintro.html', 'sourcelink.html', 'searchbox.html'], - '**': ['sidebarlogo.html', 'localtoc.html', 'relations.html', - 'sourcelink.html', 'searchbox.html'] -} - -# Additional templates that should be rendered to pages, maps page names to -# template names. -#html_additional_pages = {} - -# If false, no module index is generated. -#html_domain_indices = True - -# If false, no index is generated. -#html_use_index = True - -# If true, the index is split into individual pages for each letter. -#html_split_index = False - -# If true, links to the reST sources are added to the pages. -html_show_sourcelink = False - -# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. -html_show_sphinx = False - -# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. -#html_show_copyright = True - -# If true, an OpenSearch description file will be output, and all pages will -# contain a tag referring to it. The value of this option must be the -# base URL from which the finished HTML is served. -#html_use_opensearch = '' - -# This is the file name suffix for HTML files (e.g. ".xhtml"). -#html_file_suffix = None - -# Output file base name for HTML help builder. -htmlhelp_basename = 'sanetimedoc' - - -# -- Options for LaTeX output -------------------------------------------------- - -# The paper size ('letter' or 'a4'). -#latex_paper_size = 'letter' - -# The font size ('10pt', '11pt' or '12pt'). -#latex_font_size = '10pt' - -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, author, documentclass [howto/manual]). -latex_documents = [ - ('index', 'sanetime.tex', u'sanetime documentation', - u'HubSpot', 'manual'), -] - -# The name of an image file (relative to this directory) to place at the top of -# the title page. -#latex_logo = None - -# For "manual" documents, if this is true, then toplevel headings are parts, -# not chapters. -#latex_use_parts = False - -# If true, show page references after internal links. -#latex_show_pagerefs = False - -# If true, show URL addresses after external links. -#latex_show_urls = False - -# Additional stuff for the LaTeX preamble. -#latex_preamble = '' - -# Documents to append as an appendix to all manuals. -#latex_appendices = [] - -# If false, no module index is generated. -#latex_domain_indices = True - - -# -- Options for manual page output -------------------------------------------- - -# One entry per manual page. List of tuples -# (source start file, name, description, authors, manual section). -man_pages = [ - ('index', 'sanetime', u'sanetime documentation', - [u'HubSpot'], 1) -] - -# If true, show URL addresses after external links. -#man_show_urls = False - -# -- Options for Texinfo output ------------------------------------------------ - -# Grouping the document tree into Texinfo files. List of tuples -# (source start file, target name, title, author, -# dir menu entry, description, category) -texinfo_documents = [ - ('index', 'sanetime', u'sanetime documentation', u'HubSpot', - 'sanetime', 'One line description of project.', 'Miscellaneous'), -] - -# Documents to append as an appendix to all manuals. -texinfo_appendices = [] - -sys.path.append(os.path.abspath('_themes')) -html_theme_path = ['_themes'] -html_theme = 'kr' diff --git a/docs/dev/authors.rst b/docs/dev/authors.rst deleted file mode 100644 index 6be155f..0000000 --- a/docs/dev/authors.rst +++ /dev/null @@ -1,5 +0,0 @@ -Authors -======= - - -.. include:: ../../AUTHORS.rst \ No newline at end of file diff --git a/docs/dev/internals.rst b/docs/dev/internals.rst deleted file mode 100644 index e69de29..0000000 diff --git a/docs/dev/todo.rst b/docs/dev/todo.rst deleted file mode 100644 index 7aa2cae..0000000 --- a/docs/dev/todo.rst +++ /dev/null @@ -1,31 +0,0 @@ -How to Help -=========== - -Requests is under active development, and contributions are more than welcome! - -#. Check for open issues or open a fresh issue to start a discussion around a feature idea or a bug. - There is a Contributor Friendly tag for issues that should be ideal for people who are not very - familiar with the codebase yet. -#. Fork `the repository `_ on Github to start making your - changes to the **develop** branch (or branch off of it). -#. Write a test which shows that the bug was fixed or that the feature works as expected. -#. Send a pull request and bug the maintainer until it gets merged and published. :) - Make sure to add yourself to `AUTHORS `_. - -Development dependencies ------------------------- - -You'll need to install ``gunicorn`` and ``httpbin`` and various other dependencies in -order to run requests' test suite:: - - $ virtualenv env - $ . env/bin/activate - $ make - $ make test - -The ``Makefile`` has various useful targets for testing. - -What Needs to be Done ---------------------- - -- Documentation needs a roadmap. diff --git a/docs/index.rst b/docs/index.rst deleted file mode 100644 index df414e0..0000000 --- a/docs/index.rst +++ /dev/null @@ -1,111 +0,0 @@ -sanetime -======== - -**a sane date/time python interface** - -**sanetime** was written to DRY up all the common date/time manipulations we all do constantly in our code while offering the most simple, versatile, and intuitive client possible. - -We've all learned that the only sane way to store times is using epoch time. (You have, haven't you?) -Unfortunately, manipulating epoch time and timezones with the standard python toolset requires getting up to speed on a managerie of python modules and concepts: datetime, date, time, calendar, pytz, dateutils, timedelta, time tuples, localize, normalize. - -**sanetime** seeks to bring a more sanity to the manipulations of epoch time, timezone, time delta, and time generally. - -:: - - >>> from sanetime import time,delta # a tiny taste - - >>> time('2012-05-01 22:31',tz='America/New_York').millis - 1335925860000 - - >>> str(time(tz='Europe/London')) # now in London - '2012-05-29 15:28:05.178741 +Europe/London' - - >>> (time(2012,6,1) - time('2012-05-01')).hours - 744 - - >>> (time() + delta(h=12)).s # epoch seconds 12 hours from now - 1338344977 - -overview --------- - -time -"""" -The :ref:`time` class represents a moment in time, internally stored as microseconds since epoch. -A :ref:`time` object also has an associated timezone (UTC by default), however the timezone will never be considered during hashing, comparison or equality checks, i.e. -A moment in :ref:`time` experienced in America/New_York is equal to the same moment in :ref:`time` experienced in Europe/Dublin. - -tztime -"""""" -The :ref:`tztime` class is exactly like the :ref:`time` object, except that timezone **does** factor into equality. -A moment in `tztime` experienced in America/New_York is **not** the same as the same `tztime` moment experienced in Europe/Dublin. - - -delta -""""" -The :ref:`delta` class represents a period of time, and provides easy access to all the different ways you might slice and dice this: micros, millis, seconds, minutes, hours, mean_days, mean_weeks, mean_months, mean_years. -There are also many different flavors of these: rounded, floored, floated, positional, rounded_positional. -There is no attempt made in delta yet to be calendar aware (hence the 'mean' prefixes in some cases). - -span -"""" -The :ref:`span` class represents a window of time ranging from one specific moment in time to another specific moment in time. -You can think of it as a start :ref:`time` with a :ref:`delta`, or as a start :ref:`time` and a stop :ref:`time`. - -django -"""""" -A django model field is also provided: :ref:`SaneTimeField`, that makes it super simple to store a sanetime. -They honor the auto_add and auto_add_now features to easily turn your sanetimes into updated_at or created_at fields. -And they even work with south out of the box. - -user guide ----------- - -Use these guides to quickly get up to speed on the classes, modules, and their methods. They generally teach by example. - -.. toctree:: - :maxdepth: 2 - - user/time - user/tztime - user/delta - user/span - user/django - -.. NOTE:: - This documentation is still a work in progress. - Lots of good docs are now in place here, but there are still features lying in the code waiting documentation. - As always, the code should be treated as the ultimate source of truth. - If you haven't found what you're looking for you, you may very well find it implemented in the code. - Please feel free to help us bring it to the surface in the docs. - - - - -design principles ------------------ -* simple: simplify usecases to single method/property -* intuitive: easy to remember methods/properties, with guessable aliases - be as verbose (and communicative) or as terse (and efficient) as you want to be. for example t = time(); t.ms == t.millis == t.milliseconds -* properties whenever sensible: properties are especially useful for django, cuz you can use them directly in templates without having to stage them first in the views. - - -faq ---- -Why is everything stored internally as microseconds? - -Python's datetime gives us access to microseconds, and since milliseconds would already have us cross the 32bit integer boundary, we might as well capture everything we can and take on microseconds as well. -There are plenty of helpers on the time, tztime, and delta that make using epoch seconds or milis just as easy as using micros. - - -api documentation ------------------ - -If you are looking for information on a specific function, class or method, -this part of the documentation is for you. - -.. toctree:: - :maxdepth: 2 - - api - - diff --git a/docs/old_api.rst b/docs/old_api.rst deleted file mode 100644 index 444d277..0000000 --- a/docs/old_api.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _api: - -API -=== - -.. module:: sanetime - -.. autoclass:: time - :inherited-members: - diff --git a/docs/old_conf.py b/docs/old_conf.py deleted file mode 100644 index d182934..0000000 --- a/docs/old_conf.py +++ /dev/null @@ -1,242 +0,0 @@ -# -*- coding: utf-8 -*- -# -# sanetime documentation build configuration file, created by -# sphinx-quickstart on Sun Apr 15 15:48:39 2012. -# -# This file is execfile()d with the current directory set to its containing dir. -# -# Note that not all possible configuration values are present in this -# autogenerated file. -# -# All configuration values have a default; values that are commented out -# serve to show the default. - -import sys, os - -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -#sys.path.insert(0, os.path.abspath('.')) - -# -- General configuration ----------------------------------------------------- - -# If your documentation needs a minimal Sphinx version, state it here. -#needs_sphinx = '1.0' - -# Add any Sphinx extension module names here, as strings. They can be extensions -# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = ['sphinx.ext.autodoc'] - -# Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] - -# The suffix of source filenames. -source_suffix = '.rst' - -# The encoding of source files. -#source_encoding = 'utf-8-sig' - -# The master toctree document. -master_doc = 'index' - -# General information about the project. -project = u'sanetime' -copyright = u'2012, prior' - -# The version info for the project you're documenting, acts as replacement for -# |version| and |release|, also used in various other places throughout the -# built documents. -# -# The short X.Y version. -version = '3.5' -# The full version, including alpha/beta/rc tags. -release = '3.5.0' - -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. -#language = None - -# There are two options for replacing |today|: either, you set today to some -# non-false value, then it is used: -#today = '' -# Else, today_fmt is used as the format for a strftime call. -#today_fmt = '%B %d, %Y' - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -exclude_patterns = ['_build'] - -# The reST default role (used for this markup: `text`) to use for all documents. -#default_role = None - -# If true, '()' will be appended to :func: etc. cross-reference text. -#add_function_parentheses = True - -# If true, the current module name will be prepended to all description -# unit titles (such as .. function::). -#add_module_names = True - -# If true, sectionauthor and moduleauthor directives will be shown in the -# output. They are ignored by default. -#show_authors = False - -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' - -# A list of ignored prefixes for module index sorting. -#modindex_common_prefix = [] - - -# -- Options for HTML output --------------------------------------------------- - -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -html_theme = 'jinja' - -# Theme options are theme-specific and customize the look and feel of a theme -# further. For a list of options available for each theme, see the -# documentation. -#html_theme_options = {} - -# Add any paths that contain custom themes here, relative to this directory. -html_theme_path = ['_themes'] - -# The name for this set of Sphinx documents. If None, it defaults to -# " v documentation". -#html_title = None - -# A shorter title for the navigation bar. Default is the same as html_title. -#html_short_title = None - -# The name of an image file (relative to this directory) to place at the top -# of the sidebar. -#html_logo = None - -# The name of an image file (within the static path) to use as favicon of the -# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 -# pixels large. -#html_favicon = None - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] - -# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, -# using the given strftime format. -#html_last_updated_fmt = '%b %d, %Y' - -# If true, SmartyPants will be used to convert quotes and dashes to -# typographically correct entities. -#html_use_smartypants = True - -# Custom sidebar templates, maps document names to template names. -#html_sidebars = {} - -# Additional templates that should be rendered to pages, maps page names to -# template names. -#html_additional_pages = {} - -# If false, no module index is generated. -#html_domain_indices = True - -# If false, no index is generated. -#html_use_index = True - -# If true, the index is split into individual pages for each letter. -#html_split_index = False - -# If true, links to the reST sources are added to the pages. -#html_show_sourcelink = True - -# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. -#html_show_sphinx = True - -# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. -#html_show_copyright = True - -# If true, an OpenSearch description file will be output, and all pages will -# contain a tag referring to it. The value of this option must be the -# base URL from which the finished HTML is served. -#html_use_opensearch = '' - -# This is the file name suffix for HTML files (e.g. ".xhtml"). -#html_file_suffix = None - -# Output file base name for HTML help builder. -htmlhelp_basename = 'sanetimedoc' - - -# -- Options for LaTeX output -------------------------------------------------- - -latex_elements = { -# The paper size ('letterpaper' or 'a4paper'). -#'papersize': 'letterpaper', - -# The font size ('10pt', '11pt' or '12pt'). -#'pointsize': '10pt', - -# Additional stuff for the LaTeX preamble. -#'preamble': '', -} - -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, author, documentclass [howto/manual]). -latex_documents = [ - ('index', 'sanetime.tex', u'sanetime Documentation', - u'prior', 'manual'), -] - -# The name of an image file (relative to this directory) to place at the top of -# the title page. -#latex_logo = None - -# For "manual" documents, if this is true, then toplevel headings are parts, -# not chapters. -#latex_use_parts = False - -# If true, show page references after internal links. -#latex_show_pagerefs = False - -# If true, show URL addresses after external links. -#latex_show_urls = False - -# Documents to append as an appendix to all manuals. -#latex_appendices = [] - -# If false, no module index is generated. -#latex_domain_indices = True - - -# -- Options for manual page output -------------------------------------------- - -# One entry per manual page. List of tuples -# (source start file, name, description, authors, manual section). -man_pages = [ - ('index', 'sanetime', u'sanetime Documentation', - [u'prior'], 1) -] - -# If true, show URL addresses after external links. -#man_show_urls = False - - -# -- Options for Texinfo output ------------------------------------------------ - -# Grouping the document tree into Texinfo files. List of tuples -# (source start file, target name, title, author, -# dir menu entry, description, category) -texinfo_documents = [ - ('index', 'sanetime', u'sanetime Documentation', - u'prior', 'sanetime', 'One line description of project.', - 'Miscellaneous'), -] - -# Documents to append as an appendix to all manuals. -#texinfo_appendices = [] - -# If false, no module index is generated. -#texinfo_domain_indices = True - -# How to display URL addresses: 'footnote', 'no', or 'inline'. -#texinfo_show_urls = 'footnote' diff --git a/docs/requests_index.rst b/docs/requests_index.rst deleted file mode 100644 index 591a6a7..0000000 --- a/docs/requests_index.rst +++ /dev/null @@ -1,138 +0,0 @@ -.. Requests documentation master file, created by - sphinx-quickstart on Sun Feb 13 23:54:25 2011. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - -Requests: HTTP for Humans -========================= - -Release v\ |version|. (:ref:`Installation `) - -Requests is an :ref:`ISC Licensed ` HTTP library, written in Python, for human beings. - -Python's standard **urllib2** module provides most of -the HTTP capabilities you need, but the API is thoroughly **broken**. -It was built for a different time — and a different web. It requires an *enormous* amount of work (even method overrides) to perform the simplest of tasks. - -Things shouldn’t be this way. Not in Python. - -:: - - >>> r = requests.get('https://api.github.com/user', auth=('user', 'pass')) - >>> r.status_code - 200 - >>> r.headers['content-type'] - 'application/json; charset=utf8' - >>> r.encoding - 'utf-8' - >>> r.text - u'{"type":"User"...' - >>> r.json - {u'private_gists': 419, u'total_private_repos': 77, ...} - -See `similar code, without Requests `_. - -Requests takes all of the work out of Python HTTP/1.1 — making your integration with web services seamless. There's no need to manually add query strings to your URLs, or to form-encode your POST data. Keep-alive and HTTP connection pooling are 100% automatic, powered by `urllib3 `_, which is embedded within Requests. - - -Testimonials ------------- - -`Kippt `_, `Heroku `_, `PayPal `_, -`Transifex `_, -`Native Instruments `_, `The Washington Post `_, -`Twitter, Inc `_, -`Readability `_, and -Federal US Institutions -use Requests internally. It has been installed over 100,000 times from PyPI. - -**Armin Ronacher** - Requests is the perfect example how beautiful an API can be with the - right level of abstraction. - -**Matt DeBoard** - I'm going to get @kennethreitz's Python requests module tattooed - on my body, somehow. The whole thing. - -**Daniel Greenfeld** - Nuked a 1200 LOC spaghetti code library with 10 lines of code thanks to - @kennethreitz's request library. Today has been AWESOME. - -**Kenny Meyers** - Python HTTP: When in doubt, or when not in doubt, use Requests. Beautiful, - simple, Pythonic. - - -Feature Support ---------------- - -Requests is ready for today's web. - -- International Domains and URLs -- Keep-Alive & Connection Pooling -- Sessions with Cookie Persistence -- Browser-style SSL Verification -- Basic/Digest Authentication -- Elegant Key/Value Cookies -- Automatic Decompression -- Unicode Response Bodies -- Multipart File Uploads -- Connection Timeouts -- ``.netrc`` support -- Thread-safe. - - -User Guide ----------- - -This part of the documentation, which is mostly prose, begins with some -background information about Requests, then focuses on step-by-step -instructions for getting the most out of Requests. - -.. toctree:: - :maxdepth: 2 - - user/intro - user/install - user/quickstart - user/advanced - - -Community Guide ------------------ - -This part of the documentation, which is mostly prose, details the -Requests ecosystem and community. - -.. toctree:: - :maxdepth: 1 - - community/faq - community/out-there.rst - community/support - community/updates - -API Documentation ------------------ - -If you are looking for information on a specific function, class or method, -this part of the documentation is for you. - -.. toctree:: - :maxdepth: 2 - - api - - -Developer Guide ---------------- - -If you want to contribute to the project, this part of the documentation is for -you. - -.. toctree:: - :maxdepth: 1 - - dev/internals - dev/todo - dev/authors diff --git a/docs/time.rst b/docs/time.rst deleted file mode 100644 index e141d95..0000000 --- a/docs/time.rst +++ /dev/null @@ -1,25 +0,0 @@ -.. _time: - -construction -============ - -conversion -========== - -display -======= - - - -The time class represents a moment in time, internally stored as microseconds since epoch. -A time object also has an associated timezone (UTC by default), however the timezone will never be considered during hashing, comparison or equality checks. -A moment in time experienced in America/New_York is equal to the same moment in time experienced in Europe/Dublin. - -API -=== - -.. module:: sanetime - -.. autoclass:: time - :inherited-members: - diff --git a/docs/user/advanced.rst b/docs/user/advanced.rst deleted file mode 100644 index adda9c7..0000000 --- a/docs/user/advanced.rst +++ /dev/null @@ -1,501 +0,0 @@ -.. _advanced: - -Advanced Usage -============== - -This document covers some of Requests more advanced features. - - -Session Objects ---------------- - -The Session object allows you to persist certain parameters across -requests. It also persists cookies across all requests made from the -Session instance. - -A session object has all the methods of the main Requests API. - -Let's persist some cookies across requests:: - - s = requests.session() - - s.get('http://httpbin.org/cookies/set/sessioncookie/123456789') - r = s.get("http://httpbin.org/cookies") - - print r.text - # '{"cookies": {"sessioncookie": "123456789"}}' - - -Sessions can also be used to provide default data to the request methods:: - - headers = {'x-test': 'true'} - auth = ('user', 'pass') - - with requests.session(auth=auth, headers=headers) as c: - - # both 'x-test' and 'x-test2' are sent - c.get('http://httpbin.org/headers', headers={'x-test2': 'true'}) - - -Any dictionaries that you pass to a request method will be merged with the session-level values that are set. The method-level parameters override session parameters. - -.. admonition:: Remove a Value From a Dict Parameter - - Sometimes you'll want to omit session-level keys from a dict parameter. To do this, you simply set that key's value to ``None`` in the method-level parameter. It will automatically be omitted. - -All values that are contained within a session are directly available to you. See the :ref:`Session API Docs ` to learn more. - -Request and Response Objects ----------------------------- - -Whenever a call is made to requests.*() you are doing two major things. First, -you are constructing a ``Request`` object which will be sent of to a server -to request or query some resource. Second, a ``Response`` object is generated -once ``requests`` gets a response back from the server. The response object -contains all of the information returned by the server and also contains the -``Request`` object you created originally. Here is a simple request to get some -very important information from Wikipedia's servers:: - - >>> response = requests.get('http://en.wikipedia.org/wiki/Monty_Python') - -If we want to access the headers the server sent back to us, we do this:: - - >>> response.headers - {'content-length': '56170', 'x-content-type-options': 'nosniff', 'x-cache': - 'HIT from cp1006.eqiad.wmnet, MISS from cp1010.eqiad.wmnet', 'content-encoding': - 'gzip', 'age': '3080', 'content-language': 'en', 'vary': 'Accept-Encoding,Cookie', - 'server': 'Apache', 'last-modified': 'Wed, 13 Jun 2012 01:33:50 GMT', - 'connection': 'close', 'cache-control': 'private, s-maxage=0, max-age=0, - must-revalidate', 'date': 'Thu, 14 Jun 2012 12:59:39 GMT', 'content-type': - 'text/html; charset=UTF-8', 'x-cache-lookup': 'HIT from cp1006.eqiad.wmnet:3128, - MISS from cp1010.eqiad.wmnet:80'} - -However, if we want to get the headers we sent the server, we simply access the -request, and then the request's headers:: - - >>> response.request.headers - {'Accept-Encoding': 'identity, deflate, compress, gzip', - 'Accept': '*/*', 'User-Agent': 'python-requests/0.13.1'} - - -SSL Cert Verification ---------------------- - -Requests can verify SSL certificates for HTTPS requests, just like a web browser. To check a host's SSL certificate, you can use the ``verify`` argument:: - - >>> requests.get('https://kennethreitz.com', verify=True) - requests.exceptions.SSLError: hostname 'kennethreitz.com' doesn't match either of '*.herokuapp.com', 'herokuapp.com' - -I don't have SSL setup on this domain, so it fails. Excellent. Github does though:: - - >>> requests.get('https://github.com', verify=True) - - -You can also pass ``verify`` the path to a CA_BUNDLE file for private certs. You can also set the ``REQUESTS_CA_BUNDLE`` environment variable. - -Requests can also ignore verifying the SSL certficate if you set ``verify`` to False. :: - - >>> requests.get('https://kennethreitz.com', verify=False) - - -By default, ``verify`` is set to True. Option ``verify`` only applies to host certs. - -You can also specify the local cert file either as a path or key value pair:: - - >>> requests.get('https://kennethreitz.com', cert=('/path/server.crt', '/path/key')) - - -If you specify a wrong path or an invalid cert:: - - >>> requests.get('https://kennethreitz.com', cert='/wrong_path/server.pem') - SSLError: [Errno 336265225] _ssl.c:347: error:140B0009:SSL routines:SSL_CTX_use_PrivateKey_file:PEM lib - - -Body Content Workflow ---------------------- - -By default, when you make a request, the body of the response isn't downloaded immediately. The response headers are downloaded when you make a request, but the content isn't downloaded until you access the :class:`Response.content` attribute. - -Let's walk through it:: - - tarball_url = 'https://github.com/kennethreitz/requests/tarball/master' - r = requests.get(tarball_url) - -The request has been made, but the connection is still open. The response body has not been downloaded yet. :: - - r.content - -The content has been downloaded and cached. - -You can override this default behavior with the ``prefetch`` parameter:: - - r = requests.get(tarball_url, prefetch=True) - # Blocks until all of request body has been downloaded. - - -Configuring Requests --------------------- - -Sometimes you may want to configure a request to customize its behavior. To do -this, you can pass in a ``config`` dictionary to a request or session. See the :ref:`Configuration API Docs ` to learn more. - - -Keep-Alive ----------- - -Excellent news — thanks to urllib3, keep-alive is 100% automatic within a session! Any requests that you make within a session will automatically reuse the appropriate connection! - -Note that connections are only released back to the pool for reuse once all body data has been read; be sure to either set ``prefetch`` to ``True`` or read the ``content`` property of the ``Response`` object. - -If you'd like to disable keep-alive, you can simply set the ``keep_alive`` configuration to ``False``:: - - s = requests.session() - s.config['keep_alive'] = False - - -Asynchronous Requests ----------------------- - - -``requests.async`` has been removed from requests and is now its own repository named `GRequests `_. - - -Event Hooks ------------ - -Requests has a hook system that you can use to manipulate portions of -the request process, or signal event handling. - -Available hooks: - -``args``: - A dictionary of the arguments being sent to Request(). - -``pre_request``: - The Request object, directly before being sent. - -``post_request``: - The Request object, directly after being sent. - -``response``: - The response generated from a Request. - - -You can assign a hook function on a per-request basis by passing a -``{hook_name: callback_function}`` dictionary to the ``hooks`` request -parameter:: - - hooks=dict(args=print_url) - -That ``callback_function`` will receive a chunk of data as its first -argument. - -:: - - def print_url(args): - print args['url'] - -If an error occurs while executing your callback, a warning is given. - -If the callback function returns a value, it is assumed that it is to -replace the data that was passed in. If the function doesn't return -anything, nothing else is effected. - -Let's print some request method arguments at runtime:: - - >>> requests.get('http://httpbin.org', hooks=dict(args=print_url)) - http://httpbin.org - - -Let's hijack some arguments this time with a new callback:: - - def hack_headers(args): - if args.get('headers') is None: - args['headers'] = dict() - - args['headers'].update({'X-Testing': 'True'}) - - return args - - hooks = dict(args=hack_headers) - headers = dict(yo=dawg) - -And give it a try:: - - >>> requests.get('http://httpbin.org/headers', hooks=hooks, headers=headers) - { - "headers": { - "Content-Length": "", - "Accept-Encoding": "gzip", - "Yo": "dawg", - "X-Forwarded-For": "::ffff:24.127.96.129", - "Connection": "close", - "User-Agent": "python-requests.org", - "Host": "httpbin.org", - "X-Testing": "True", - "X-Forwarded-Protocol": "", - "Content-Type": "" - } - } - - -Custom Authentication ---------------------- - -Requests allows you to use specify your own authentication mechanism. - -Any callable which is passed as the ``auth`` argument to a request method will -have the opportunity to modify the request before it is dispatched. - -Authentication implementations are subclasses of ``requests.auth.AuthBase``, -and are easy to define. Requests provides two common authentication scheme -implementations in ``requests.auth``: ``HTTPBasicAuth`` and ``HTTPDigestAuth``. - -Let's pretend that we have a web service that will only respond if the -``X-Pizza`` header is set to a password value. Unlikely, but just go with it. - -:: - - from requests.auth import AuthBase - class PizzaAuth(AuthBase): - """Attaches HTTP Pizza Authentication to the given Request object.""" - def __init__(self, username): - # setup any auth-related data here - self.username = username - - def __call__(self, r): - # modify and return the request - r.headers['X-Pizza'] = self.username - return r - -Then, we can make a request using our Pizza Auth:: - - >>> requests.get('http://pizzabin.org/admin', auth=PizzaAuth('kenneth')) - - -Streaming Requests ------------------- - -With ``requests.Response.iter_lines()`` you can easily iterate over streaming -APIs such as the `Twitter Streaming API `_. - -To use the Twitter Streaming API to track the keyword "requests": - -:: - - import requests - import json - - r = requests.post('https://stream.twitter.com/1/statuses/filter.json', - data={'track': 'requests'}, auth=('username', 'password')) - - for line in r.iter_lines(): - if line: # filter out keep-alive new lines - print json.loads(line) - - -Verbose Logging ---------------- - -If you want to get a good look at what HTTP requests are being sent -by your application, you can turn on verbose logging. - -To do so, just configure Requests with a stream to write to:: - - >>> my_config = {'verbose': sys.stderr} - >>> requests.get('http://httpbin.org/headers', config=my_config) - 2011-08-17T03:04:23.380175 GET http://httpbin.org/headers - - - -Proxies -------- - -If you need to use a proxy, you can configure individual requests with the -``proxies`` argument to any request method: - -:: - - import requests - - proxies = { - "http": "10.10.1.10:3128", - "https": "10.10.1.10:1080", - } - - requests.get("http://example.org", proxies=proxies) - -You can also configure proxies by environment variables ``HTTP_PROXY`` and ``HTTPS_PROXY``. - -:: - - $ export HTTP_PROXY="10.10.1.10:3128" - $ export HTTPS_PROXY="10.10.1.10:1080" - $ python - >>> import requests - >>> requests.get("http://example.org") - -To use HTTP Basic Auth with your proxy, use the `http://user:password@host/` syntax: - -:: - - proxies = { - "http": "http://user:pass@10.10.1.10:3128/", - } - - -HTTP Verbs ----------- - -Requests provides access to almost the full range of HTTP verbs: GET, OPTIONS, -HEAD, POST, PUT, PATCH and DELETE. The following provides detailed examples of -using these various verbs in Requests, using the GitHub API. - -We will begin with the verb most commonly used: GET. HTTP GET is an idempotent -method that returns a resource from a given URL. As a result, it is the verb -you ought to use when attempting to retrieve data from a web location. An -example usage would be attempting to get information about a specific commit -from GitHub. Suppose we wanted commit ``a050faf`` on Requests. We would get it -like so:: - - >>> import requests - >>> r = requests.get('https://api.github.com/repos/kennethreitz/requests/git/commits/a050faf084662f3a352dd1a941f2c7c9f886d4ad') - -We should confirm that GitHub responded correctly. If it has, we want to work -out what type of content it is. Do this like so:: - - >>> if (r.status_code == requests.codes.ok): - ... print r.headers['content-type'] - ... - application/json; charset=utf-8 - -So, GitHub returns JSON. That's great, we can use the JSON module to turn it -into Python objects. Because GitHub returned UTF-8, we should use the -``r.text`` method, not the ``r.content`` method. ``r.content`` returns a -bytestring, while ``r.text`` returns a Unicode-encoded string. I have no plans -to perform byte-manipulation on this response, so I want any Unicode code -points encoded.:: - - >>> import json - >>> commit_data = json.loads(r.text) - >>> print commit_data.keys() - [u'committer', u'author', u'url', u'tree', u'sha', u'parents', u'message'] - >>> print commit_data[u'committer'] - {u'date': u'2012-05-10T11:10:50-07:00', u'email': u'me@kennethreitz.com', u'name': u'Kenneth Reitz'} - >>> print commit_data[u'message'] - makin' history - -So far, so simple. Well, let's investigate the GitHub API a little bit. Now, -we could look at the documentation, but we might have a little more fun if we -use Requests instead. We can take advantage of the Requests OPTIONS verb to -see what kinds of HTTP methods are supported on the url we just used.:: - - >>> verbs = requests.options(r.url) - >>> verbs.status_code - 500 - -Uh, what? That's unhelpful! Turns out GitHub, like many API providers, don't -actually implement the OPTIONS method. This is an annoying oversight, but it's -OK, we can just use the boring documentation. If GitHub had correctly -implemented OPTIONS, however, they should return the allowed methods in the -headers, e.g.:: - - >>> verbs = requests.options('http://a-good-website.com/api/cats') - >>> print verbs.headers['allow'] - GET,HEAD,POST,OPTIONS - -Turning to the documentation, we see that the only other method allowed for -commits is POST, which creates a new commit. As we're using the Requests repo, -we should probably avoid making ham-handed POSTS to it. Instead, let's play -with the Issues feature of GitHub. - -This documentation was added in response to Issue #482. Given that this issue -already exists, we will use it as an example. Let's start by getting it.:: - - >>> r = requests.get('https://api.github.com/repos/kennethreitz/requests/issues/482') - >>> r.status_code - 200 - >>> issue = json.loads(r.text) - >>> print issue[u'title'] - Feature any http verb in docs - >>> print issue[u'comments'] - 3 - -Cool, we have three comments. Let's take a look at the last of them.:: - - >>> r = requests.get(r.url + u'/comments') - >>> r.status_code - 200 - >>> comments = json.loads(r.text) - >>> print comments[0].keys() - [u'body', u'url', u'created_at', u'updated_at', u'user', u'id'] - >>> print comments[2][u'body'] - Probably in the "advanced" section - -Well, that seems like a silly place. Let's post a comment telling the poster -that he's silly. Who is the poster, anyway?:: - - >>> print comments[2][u'user'][u'login'] - kennethreitz - -OK, so let's tell this Kenneth guy that we think this example should go in the -quickstart guide instead. According to the GitHub API doc, the way to do this -is to POST to the thread. Let's do it.:: - - >>> body = json.dumps({u"body": u"Sounds great! I'll get right on it!"}) - >>> url = u"https://api.github.com/repos/kennethreitz/requests/issues/482/comments" - >>> r = requests.post(url=url, data=body) - >>> r.status_code - 404 - -Huh, that's weird. We probably need to authenticate. That'll be a pain, right? -Wrong. Requests makes it easy to use many forms of authentication, including -the very common Basic Auth.:: - - >>> from requests.auth import HTTPBasicAuth - >>> auth = HTTPBasicAuth('fake@example.com', 'not_a_real_password') - >>> r = requests.post(url=url, data=body, auth=auth) - >>> r.status_code - 201 - >>> content = json.loads(r.text) - >>> print content[u'body'] - Sounds great! I'll get right on it. - -Brilliant. Oh, wait, no! I meant to add that it would take me a while, because -I had to go feed my cat. If only I could edit this comment! Happily, GitHub -allows us to use another HTTP verb, PATCH, to edit this comment. Let's do -that.:: - - >>> print content[u"id"] - 5804413 - >>> body = json.dumps({u"body": u"Sounds great! I'll get right on it once I feed my cat."}) - >>> url = u"https://api.github.com/repos/kennethreitz/requests/issues/comments/5804413" - >>> r = requests.patch(url=url, data=body, auth=auth) - >>> r.status_code - 200 - -Excellent. Now, just to torture this Kenneth guy, I've decided to let him -sweat and not tell him that I'm working on this. That means I want to delete -this comment. GitHub lets us delete comments using the incredibly aptly named -DELETE method. Let's get rid of it.:: - - >>> r = requests.delete(url=url, auth=auth) - >>> r.status_code - 204 - >>> r.headers['status'] - '204 No Content' - -Excellent. All gone. The last thing I want to know is how much of my ratelimit -I've used. Let's find out. GitHub sends that information in the headers, so -rather than download the whole page I'll send a HEAD request to get the -headers.:: - - >>> r = requests.head(url=url, auth=auth) - >>> print r.headers - // ...snip... // - 'x-ratelimit-remaining': '4995' - 'x-ratelimit-limit': '5000' - // ...snip... // - -Excellent. Time to write a Python program that abuses the GitHub API in all -kinds of exciting ways, 4995 more times. diff --git a/docs/user/install.rst b/docs/user/install.rst deleted file mode 100644 index 8da91e1..0000000 --- a/docs/user/install.rst +++ /dev/null @@ -1,56 +0,0 @@ -.. _install: - -Installation -============ - -This part of the documentation covers the installation of Requests. -The first step to using any software package is getting it properly installed. - - -Distribute & Pip ----------------- - -Installing requests is simple with `pip `_:: - - $ pip install requests - -or, with `easy_install `_:: - - $ easy_install requests - -But, you really `shouldn't do that `_. - - - -Cheeseshop Mirror ------------------ - -If the Cheeseshop is down, you can also install Requests from Kenneth Reitz's -personal `Cheeseshop mirror `_:: - - $ pip install -i http://pip.kennethreitz.com/simple requests - - -Get the Code ------------- - -Requests is actively developed on GitHub, where the code is -`always available `_. - -You can either clone the public repository:: - - git clone git://github.com/kennethreitz/requests.git - -Download the `tarball `_:: - - $ curl -OL https://github.com/kennethreitz/requests/tarball/master - -Or, download the `zipball `_:: - - $ curl -OL https://github.com/kennethreitz/requests/zipball/master - - -Once you have a copy of the source, you can embed it in your Python package, -or install it into your site-packages easily:: - - $ python setup.py install diff --git a/docs/user/intro.rst b/docs/user/intro.rst deleted file mode 100644 index 15a1779..0000000 --- a/docs/user/intro.rst +++ /dev/null @@ -1,49 +0,0 @@ -.. _introduction: - -Introduction -============ - -Philosophy ----------- - -Requests was developed with a few :pep:`20` idioms in mind. - - -#. Beautiful is better than ugly. -#. Explicit is better than implicit. -#. Simple is better than complex. -#. Complex is better than complicated. -#. Readability counts. - -All contributions to Requests should keep these important rules in mind. - - -ISC License ------------ - -A large number of open source projects you find today are `GPL Licensed`_. -While the GPL has its time and place, it should most certainly not be your -go-to license for your next open source project. - -A project that is released as GPL cannot be used in any commercial product -without the product itself also being offered as open source. - -The MIT, BSD, ISC, and Apache2 licenses are great alternatives to the GPL -that allow your open-source software to be used freely in proprietary, -closed-source software. - -Requests is released under terms of `The ISC License`_. - -.. _`GPL Licensed`: http://www.opensource.org/licenses/gpl-license.php -.. _`The ISC License`: http://www.opensource.org/licenses/isc-license - - -Requests License ----------------- - - Copyright (c) 2011, Kenneth Reitz - - Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies. - - THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. - diff --git a/docs/user/quickstart.rst b/docs/user/quickstart.rst deleted file mode 100644 index d3e786c..0000000 --- a/docs/user/quickstart.rst +++ /dev/null @@ -1,452 +0,0 @@ -.. _quickstart: - -Quickstart -========== - -.. module:: requests.models - -Eager to get started? This page gives a good introduction in how to get started -with Requests. This assumes you already have Requests installed. If you do not, -head over to the :ref:`Installation ` section. - -First, make sure that: - -* Requests is :ref:`installed ` -* Requests is :ref:`up-to-date ` - - -Let's get started with some simple examples. - - -Make a Request ------------------- - -Making a request with Requests is very simple. - -Begin by importing the Requests module:: - - >>> import requests - -Now, let's try to get a webpage. For this example, let's get GitHub's public -timeline :: - - >>> r = requests.get('https://github.com/timeline.json') - -Now, we have a :class:`Response` object called ``r``. We can get all the -information we need from this object. - -Requests' simple API means that all forms of HTTP request are as obvious. For -example, this is how you make an HTTP POST request:: - - >>> r = requests.post("http://httpbin.org/post") - -Nice, right? What about the other HTTP request types: PUT, DELETE, HEAD and -OPTIONS? These are all just as simple:: - - >>> r = requests.put("http://httpbin.org/put") - >>> r = requests.delete("http://httpbin.org/delete") - >>> r = requests.head("http://httpbin.org/get") - >>> r = requests.options("http://httpbin.org/get") - -That's all well and good, but it's also only the start of what Requests can -do. - - -Passing Parameters In URLs --------------------------- - -You often want to send some sort of data in the URL's query string. If -you were constructing the URL by hand, this data would be given as key/value -pairs in the URL after a question mark, e.g. ``httpbin.org/get?key=val``. -Requests allows you to provide these arguments as a dictionary, using the -``params`` keyword argument. As an example, if you wanted to pass -``key1=value1`` and ``key2=value2`` to ``httpbin.org/get``, you would use the -following code:: - - >>> payload = {'key1': 'value1', 'key2': 'value2'} - >>> r = requests.get("http://httpbin.org/get", params=payload) - -You can see that the URL has been correctly encoded by printing the URL:: - - >>> print r.url - u'http://httpbin.org/get?key2=value2&key1=value1' - - -Response Content ----------------- - -We can read the content of the server's response. Consider the GitHub timeline -again:: - - >>> import requests - >>> r = requests.get('https://github.com/timeline.json') - >>> r.text - '[{"repository":{"open_issues":0,"url":"https://github.com/... - -Requests will automatically decode content from the server. Most unicode -charsets are seamlessly decoded. - -When you make a request, ``r.encoding`` is set, based on the HTTP headers. -Requests will use that encoding when you access ``r.text``. If ``r.encoding`` -is ``None``, Requests will make an extremely educated guess of the encoding -of the response body. You can manually set ``r.encoding`` to any encoding -you'd like, and that charset will be used. - - -Binary Response Content ------------------------ - -You can also access the response body as bytes, for non-text requests:: - - >>> r.content - b'[{"repository":{"open_issues":0,"url":"https://github.com/... - -The ``gzip`` and ``deflate`` transfer-encodings are automatically decoded for you. - -For example, to create an image from binary data returned by a request, you can -use the following code: - - >>> from PIL import Image - >>> from StringIO import StringIO - >>> i = Image.open(StringIO(r.content)) - - -JSON Response Content ---------------------- - -There's also a builtin JSON decoder, in case you're dealing with JSON data:: - - >>> import requests - >>> r = requests.get('https://github.com/timeline.json') - >>> r.json - [{u'repository': {u'open_issues': 0, u'url': 'https://github.com/... - -In case the JSON decoding fails, ``r.json`` simply returns ``None``. - - -Raw Response Content --------------------- - -In the rare case that you'd like to get the absolute raw socket response from the server, -you can access ``r.raw``:: - - >>> r.raw - - - >>> r.raw.read(10) - '\x1f\x8b\x08\x00\x00\x00\x00\x00\x00\x03' - - -Custom Headers --------------- - -If you'd like to add HTTP headers to a request, simply pass in a ``dict`` to the -``headers`` parameter. - -For example, we didn't specify our content-type in the previous example:: - - >>> import json - >>> url = 'https://api.github.com/some/endpoint' - >>> payload = {'some': 'data'} - >>> headers = {'content-type': 'application/json'} - - >>> r = requests.post(url, data=json.dumps(payload), headers=headers) - - -More complicated POST requests ------------------------------- - -Typically, you want to send some form-encoded data — much like an HTML form. -To do this, simply pass a dictionary to the `data` argument. Your -dictionary of data will automatically be form-encoded when the request is made:: - - >>> payload = {'key1': 'value1', 'key2': 'value2'} - >>> r = requests.post("http://httpbin.org/post", data=payload) - >>> print r.text - { - // ...snip... // - "form": { - "key2": "value2", - "key1": "value1" - }, - // ...snip... // - } - -There are many times that you want to send data that is not form-encoded. If you pass in a ``string`` instead of a ``dict``, that data will be posted directly. - -For example, the GitHub API v3 accepts JSON-Encoded POST/PATCH data:: - - >>> import json - >>> url = 'https://api.github.com/some/endpoint' - >>> payload = {'some': 'data'} - - >>> r = requests.post(url, data=json.dumps(payload)) - - -POST a Multipart-Encoded File ------------------------------ - -Requests makes it simple to upload Multipart-encoded files:: - - >>> url = 'http://httpbin.org/post' - >>> files = {'report.xls': open('report.xls', 'rb')} - - >>> r = requests.post(url, files=files) - >>> r.text - { - // ...snip... // - "files": { - "report.xls": "" - }, - // ...snip... // - } - -You can set the filename explicitly:: - - >>> url = 'http://httpbin.org/post' - >>> files = {'file': ('report.xls', open('report.xls', 'rb'))} - - >>> r = requests.post(url, files=files) - >>> r.text - { - // ...snip... // - "files": { - "file": "" - }, - // ...snip... // - } - -If you want, you can send strings to be received as files:: - - >>> url = 'http://httpbin.org/post' - >>> files = {'file': ('report.csv', 'some,data,to,send\nanother,row,to,send\n')} - - >>> r = requests.post(url, files=files) - >>> r.text - { - // ...snip... // - "files": { - "file": "some,data,to,send\\nanother,row,to,send\\n" - }, - // ...snip... // - } - - -Response Status Codes ---------------------- - -We can check the response status code:: - - >>> r = requests.get('http://httpbin.org/get') - >>> r.status_code - 200 - -Requests also comes with a built-in status code lookup object for easy -reference:: - - >>> r.status_code == requests.codes.ok - True - -If we made a bad request (non-200 response), we can raise it with -:class:`Response.raise_for_status()`:: - - >>> _r = requests.get('http://httpbin.org/status/404') - >>> _r.status_code - 404 - - >>> _r.raise_for_status() - Traceback (most recent call last): - File "requests/models.py", line 832, in raise_for_status - raise http_error - requests.exceptions.HTTPError: 404 Client Error - -But, since our ``status_code`` for ``r`` was ``200``, when we call -``raise_for_status()`` we get:: - - >>> r.raise_for_status() - None - -All is well. - - -Response Headers ----------------- - -We can view the server's response headers using a Python dictionary:: - - >>> r.headers - { - 'status': '200 OK', - 'content-encoding': 'gzip', - 'transfer-encoding': 'chunked', - 'connection': 'close', - 'server': 'nginx/1.0.4', - 'x-runtime': '148ms', - 'etag': '"e1ca502697e5c9317743dc078f67693f"', - 'content-type': 'application/json; charset=utf-8' - } - -The dictionary is special, though: it's made just for HTTP headers. According to -`RFC 2616 `_, HTTP -Headers are case-insensitive. - -So, we can access the headers using any capitalization we want:: - - >>> r.headers['Content-Type'] - 'application/json; charset=utf-8' - - >>> r.headers.get('content-type') - 'application/json; charset=utf-8' - -If a header doesn't exist in the Response, its value defaults to ``None``:: - - >>> r.headers['X-Random'] - None - - -Cookies -------- - -If a response contains some Cookies, you can get quick access to them:: - - >>> url = 'http://httpbin.org/cookies/set/requests-is/awesome' - >>> r = requests.get(url) - - >>> r.cookies['requests-is'] - 'awesome' - -To send your own cookies to the server, you can use the ``cookies`` -parameter:: - - >>> url = 'http://httpbin.org/cookies' - >>> cookies = dict(cookies_are='working') - - >>> r = requests.get(url, cookies=cookies) - >>> r.text - '{"cookies": {"cookies_are": "working"}}' - - -Basic Authentication --------------------- - -Many web services require authentication. There many different types of -authentication, but the most common is HTTP Basic Auth. - -Making requests with Basic Auth is extremely simple:: - - >>> from requests.auth import HTTPBasicAuth - >>> requests.get('https://api.github.com/user', auth=HTTPBasicAuth('user', 'pass')) - - -Due to the prevalence of HTTP Basic Auth, requests provides a shorthand for -this authentication method:: - - >>> requests.get('https://api.github.com/user', auth=('user', 'pass')) - - -Providing the credentials as a tuple in this fashion is functionally equivalent -to the ``HTTPBasicAuth`` example above. - - -Digest Authentication ---------------------- - -Another popular form of web service protection is Digest Authentication:: - - >>> from requests.auth import HTTPDigestAuth - >>> url = 'http://httpbin.org/digest-auth/auth/user/pass' - >>> requests.get(url, auth=HTTPDigestAuth('user', 'pass')) - - - -OAuth Authentication --------------------- - -Miguel Araujo's `requests-oauth `_ -project provides a simple interface for establishing OAuth connections. -Documentation and examples can be found on the requests-oauth -`git repository `_. - - -Redirection and History ------------------------ - -Requests will automatically perform location redirection while using the GET -and OPTIONS verbs. - -GitHub redirects all HTTP requests to HTTPS. We can use the ``history`` method -of the Response object to track redirection. Let's see what Github does:: - - >>> r = requests.get('http://github.com') - >>> r.url - 'https://github.com/' - >>> r.status_code - 200 - >>> r.history - [] - -The :class:`Response.history` list contains a list of the -:class:`Request` objects that were created in order to complete the request. The list is sorted from the oldest to the most recent request. - -If you're using GET or OPTIONS, you can disable redirection handling with the -``allow_redirects`` parameter:: - - >>> r = requests.get('http://github.com', allow_redirects=False) - >>> r.status_code - 301 - >>> r.history - [] - -If you're using POST, PUT, PATCH, DELETE or HEAD, you can enable -redirection as well:: - - >>> r = requests.post('http://github.com', allow_redirects=True) - >>> r.url - 'https://github.com/' - >>> r.history - [] - - -Timeouts --------- - -You can tell requests to stop waiting for a response after a given number of -seconds with the ``timeout`` parameter:: - - >>> requests.get('http://github.com', timeout=0.001) - Traceback (most recent call last): - File "", line 1, in - requests.exceptions.Timeout: Request timed out. - -.. admonition:: Note: - - ``timeout`` only effects the connection process itself, not the - downloading of the response body. - - -Errors and Exceptions ---------------------- - -In the event of a network problem (e.g. DNS failure, refused connection, etc), -Requests will raise a :class:`ConnectionError` exception. - -In the event of the rare invalid HTTP response, Requests will raise -an :class:`HTTPError` exception. - -If a request times out, a :class:`Timeout` exception is raised. - -If a request exceeds the configured number of maximum redirections, a -:class:`TooManyRedirects` exception is raised. - -All exceptions that Requests explicitly raises inherit from -:class:`requests.exceptions.RequestException`. - -You can refer to :ref:`Configuration API Docs ` for immediate -raising of :class:`HTTPError` exceptions via the ``danger_mode`` option or -have Requests catch the majority of -:class:`requests.exceptions.RequestException` exceptions with the ``safe_mode`` -option. - ------------------------ - -Ready for more? Check out the :ref:`advanced ` section. diff --git a/docs/user/time.rst b/docs/user/time.rst deleted file mode 100644 index 2addfe5..0000000 --- a/docs/user/time.rst +++ /dev/null @@ -1,179 +0,0 @@ -.. _time: - -time -==== - -The ``time`` class represents a moment in time, internally stored as microseconds since epoch. -A ``time`` object also has an associated timezone (UTC by default), however the timezone will never be considered during hashing, comparison or equality checks, i.e. -A moment in ``time`` experienced in America/New_York is equal to the same moment in ``time`` experienced in Europe/Dublin. - -:: - - >>> from sanetime import time - -construction ------------- - -You can construct a sanetime object from epoch times, datetimes, date/time parts, or from a parseable string. - -Epoch microseconds are assumed when no keyword is given. -Intuitive aliases exists for kwargs, be as terse or verbose as you want (us = micros = epoch_micros = epoch_microseconds): - -:: - - >>> time(1338508800000000) - SaneTime(1338508800000000,) - - >>> time(micros=1338508800000000) - SaneTime(1338508800000000,) - - >>> time(millis=1338508800000) - SaneTime(1338508800000000,) - - >>> time(seconds=1338508800) - SaneTime(1338508800000000,) - - >>> time(minutes=22308480, tz='America/New_York') - SaneTime(1338508800000000,) - - -If you have the calendar parameters, then construct just as you would a datetime: - -:: - - >>> time(2012,1,1) - SaneTime(1325376000000000,) - - >>> time(2012,1,1,12,30,1) - SaneTime(1325421001000000,) - - >>> time(2012,1,1,12,30,1,1, tz='America/New_York') - SaneTime(1325421001000001,) - - -If you already have a datetime object, just construct from that: - -:: - - >>> dt = datetime(2012,1,1) - >>> time(dt) - SaneTime(1325376000000000,) - - -Or construct from a parsable string: - -:: - - >>> time('January 1st, 2012 12:30:01pm') - SaneTime(1325421001000000,) - - >>> time('January 1st, 2012 12:30:01pm', tz='America/New_York') - SaneTime(1325421001000000,) - - -arithmetic ----------- - -Adding any int/long assumes it to be in microseconds. You can also add any :ref:`delta`: - -:: - - >>> time(2012,1,1) + 5 - SaneTime(1325376000000005,) - - >>> time(2012,1,1) + delta(hours=5) - SaneTime(1325394000000000,) - - -Subtracting two sanetimes produces a :ref:`delta`: - -:: - - >>> time() - time(2012,1,1) # time since new year - SaneDelta(15131339063956) - - >>> abs(time() - time()).micros # microseconds to construct a time - 30 - - -conversion ----------- - -You can easily convert to a timezone-aware datetime or to a naive datetime. They are accessed as properties. - -:: - - >>> time(2012,1,1,tz='America/Los_Angeles').datetime - datetime.datetime(2012, 1, 1, 0, 0, tzinfo=) - - >>> time(2012,1,1,tz='America/Los_Angeles').naive_datetime - datetime.datetime(2012, 1, 1, 0, 0) - - -There are other convenience datetime timezone conversions as well. - -:: - - >>> time(2012,1,1,tz='America/Los_Angeles').utc_datetime - datetime.datetime(2012, 1, 1, 8, 0, tzinfo=) - - >>> time(2012,1,1,tz='America/Los_Angeles').utc_naive_datetime - datetime.datetime(2012, 1, 1, 8, 0) - - >>> time(2012,1,1,tz='America/Los_Angeles').ny_datetime - datetime.datetime(2012, 1, 1, 3, 0, tzinfo=) - - >>> time(2012,1,1,tz='America/Los_Angeles').ny_naive_datetime - datetime.datetime(2012, 1, 1, 3, 0) - - -To epoch times: - -:: - - >>> time(2012,1,1).minutes - 22089600 - - >>> time(2012,1,1).seconds - 1325376000 - - >>> time(2012,1,1).millis - 1325376000000 - - >>> time(2012,1,1).micros - 1325376000000000 - -long and int conversion just bring back the epoch microseconds - -:: - - >>> int(time(2012,1,1)) - 1325376000000000 - - >>> long(time(2012,1,1)) - 1325376000000000L - - -date/time parts ---------------- - -You can get at any of the date parts just as you might with datetime properties. Be careful-- these properties are all singular. Do not confuse with the plural epoch possiblities of the previous section. (this ambiguity will be fixed in future versions) - -:: - - >>> time().year - 2012 - >>> time().month - 6 - >>> time().day - 24 - >>> time().hour - 3 - >>> time().minute - 42 - >>> time().second - 12 - >>> time().micro - 664819 - - diff --git a/publish_docs.py b/publish_docs.py deleted file mode 100755 index bfc784e..0000000 --- a/publish_docs.py +++ /dev/null @@ -1,27 +0,0 @@ -#!/usr/bin/env python -import subprocess - -def call(args, shell=False): - if isinstance(args, basestring): - pcmd = args - else: - pcmd = ' '.join(args) - print("== attempting == %s =="%pcmd) - if subprocess.call(args, shell=shell): - print("== !problem! == %s ==" % pcmd) - exit(1) - print("== done == %s ==" % pcmd) - print - -call(['git', 'checkout', 'master']) -call(['make', '-C', 'docs', 'html']) -call(['rm', '-rf', '/tmp/docs_html']) -call(['cp', '-R', 'docs/_build/html', '/tmp/docs_html']) -call(['git', 'checkout', 'gh-pages']) -call('rm -rf *', True) -call('cp -R /tmp/docs_html/* .', True) -call(['git', 'add', '.']) -call(['git', 'commit', '-a', '-v']) -call(['git', 'push']) -call(['git', 'checkout', 'master']) - diff --git a/setup.py b/setup.py index 6c58c9c..781dafc 100755 --- a/setup.py +++ b/setup.py @@ -1,7 +1,7 @@ #!/usr/bin/env python from setuptools import setup, find_packages -__VERSION__ = '4.2.0' +__VERSION__ = '4.2.1' setup( name='sanetime', @@ -15,7 +15,7 @@ download_url='https://github.com/HubSpot/sanetime/tarball/v%s'%__VERSION__, license=open('LICENSE').read(), description='A sane date/time python interface: better epoch time, timezones, and deltas -- django support as well', - long_description=open('README.rst').read(), + long_description=open('README.markdown').read(), install_requires=[ 'pytz>=2010', 'python-dateutil>=1.5,<2.0', # we're not compatible with python 3.0 yet