| Server IP : 82.208.35.60 / Your IP : 216.73.217.33 Web Server : Apache/2.4.55 (FreeBSD) OpenSSL/1.1.1q-freebsd PHP/7.3.31 System : FreeBSD server7.d2m.cz 12.4-RELEASE-p9 FreeBSD 12.4-RELEASE-p9 GENERIC amd64 User : studiokobylisy_cz ( 1008) PHP Version : 7.3.31 Disable Function : NONE MySQL : OFF | cURL : ON | WGET : OFF | Perl : OFF | Python : OFF | Sudo : OFF | Pkexec : OFF Directory : /usr/local/share/doc/requests-toolbelt/ |
Upload File : |
<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>User-Agent Constructor — requests_toolbelt 0.8.0 documentation</title>
<script type="text/javascript" src="_static/js/modernizr.min.js"></script>
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT:'./',
VERSION:'0.8.0',
LANGUAGE:'None',
COLLAPSE_INDEX:false,
FILE_SUFFIX:'.html',
HAS_SOURCE: true,
SOURCELINK_SUFFIX: '.txt'
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<script type="text/javascript" src="_static/js/theme.js"></script>
<link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="prev" title="Uploading Data" href="uploading-data.html" />
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" >
<a href="index.html" class="icon icon-home"> requests_toolbelt
</a>
<div class="version">
0.8.0
</div>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
<input type="text" name="q" placeholder="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
<ul>
<li class="toctree-l1"><a class="reference internal" href="user.html">requests toolbelt</a></li>
<li class="toctree-l1"><a class="reference internal" href="contributing.html">Contributing to this project</a></li>
</ul>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="adapters.html">Transport Adapters</a></li>
<li class="toctree-l1"><a class="reference internal" href="authentication.html">Authentication</a></li>
<li class="toctree-l1"><a class="reference internal" href="deprecated.html">Deprecated Requests Utilities</a></li>
<li class="toctree-l1"><a class="reference internal" href="downloadutils.html">Utilities for Downloading Streaming Responses</a></li>
<li class="toctree-l1"><a class="reference internal" href="dumputils.html">Utilities for Dumping Information About Responses</a></li>
<li class="toctree-l1"><a class="reference internal" href="formdata.html">Utilities for Enhanced Form-Data Serialization</a></li>
<li class="toctree-l1"><a class="reference internal" href="exceptions.html">Custom Toolbelt Exceptions</a></li>
<li class="toctree-l1"><a class="reference internal" href="sessions.html">Specialized Sessions</a></li>
<li class="toctree-l1"><a class="reference internal" href="threading.html">Using requests with Threading</a></li>
<li class="toctree-l1"><a class="reference internal" href="uploading-data.html">Uploading Data</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">User-Agent Constructor</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#adding-extra-information-to-your-user-agent-string">Adding Extra Information to Your User-Agent String</a></li>
<li class="toctree-l2"><a class="reference internal" href="#selecting-only-what-you-want">Selecting Only What You Want</a></li>
</ul>
</li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
<nav class="wy-nav-top" aria-label="top navigation">
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="index.html">requests_toolbelt</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="index.html">Docs</a> »</li>
<li>User-Agent Constructor</li>
<li class="wy-breadcrumbs-aside">
<a href="_sources/user-agent.rst.txt" rel="nofollow"> View page source</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<div class="section" id="user-agent-constructor">
<span id="user-agent"></span><h1>User-Agent Constructor<a class="headerlink" href="#user-agent-constructor" title="Permalink to this headline">¶</a></h1>
<p>Having well-formed user-agent strings is important for the proper functioning
of the web. Make server administators happy by generating yourself a nice
user-agent string, just like Requests does! The output of the user-agent
generator looks like this:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">import</span> <span class="nn">requests_toolbelt</span>
<span class="gp">>>> </span><span class="n">requests_toolbelt</span><span class="o">.</span><span class="n">user_agent</span><span class="p">(</span><span class="s1">'mypackage'</span><span class="p">,</span> <span class="s1">'0.0.1'</span><span class="p">)</span>
<span class="go">'mypackage/0.0.1 CPython/2.7.5 Darwin/13.0.0'</span>
</pre></div>
</div>
<p>The Python type and version, and the platform type and version, will accurately
reflect the system that your program is running on. You can drop this easily
into your program like this:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">requests_toolbelt</span> <span class="k">import</span> <span class="n">user_agent</span>
<span class="kn">from</span> <span class="nn">requests</span> <span class="k">import</span> <span class="n">Session</span>
<span class="n">s</span> <span class="o">=</span> <span class="n">Session</span><span class="p">()</span>
<span class="n">s</span><span class="o">.</span><span class="n">headers</span> <span class="o">=</span> <span class="p">{</span>
<span class="s1">'User-Agent'</span><span class="p">:</span> <span class="n">user_agent</span><span class="p">(</span><span class="s1">'my_package'</span><span class="p">,</span> <span class="s1">'0.0.1'</span><span class="p">)</span>
<span class="p">}</span>
<span class="n">r</span> <span class="o">=</span> <span class="n">s</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">'https://api.github.com/users'</span><span class="p">)</span>
</pre></div>
</div>
<p>This will override the default Requests user-agent string for all of your HTTP
requests, replacing it with your own.</p>
<div class="section" id="adding-extra-information-to-your-user-agent-string">
<h2>Adding Extra Information to Your User-Agent String<a class="headerlink" href="#adding-extra-information-to-your-user-agent-string" title="Permalink to this headline">¶</a></h2>
<div class="versionadded">
<p><span class="versionmodified">New in version 0.5.0.</span></p>
</div>
<p>If you feel it necessary, you can also include versions for other things that
your client is using. For example if you were building a package and wanted to
include the package name and version number as well as the version of requests
and requests-toolbelt you were using you could do the following:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">requests</span>
<span class="kn">import</span> <span class="nn">requests_toolbelt</span>
<span class="kn">from</span> <span class="nn">requests_toolbelt.utils</span> <span class="kn">import</span> <span class="n">user_agent</span> <span class="k">as</span> <span class="n">ua</span>
<span class="n">user_agent</span> <span class="o">=</span> <span class="n">ua</span><span class="o">.</span><span class="n">user_agent</span><span class="p">(</span><span class="s1">'mypackage'</span><span class="p">,</span> <span class="s1">'0.0.1'</span><span class="p">,</span>
<span class="n">extras</span><span class="o">=</span><span class="p">[(</span><span class="s1">'requests'</span><span class="p">,</span> <span class="n">requests</span><span class="o">.</span><span class="n">__version__</span><span class="p">),</span>
<span class="p">(</span><span class="s1">'requests-toolbelt'</span><span class="p">,</span> <span class="n">requests_toolbelt</span><span class="o">.</span><span class="n">__version__</span><span class="p">)])</span>
<span class="n">s</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">Session</span><span class="p">()</span>
<span class="n">s</span><span class="o">.</span><span class="n">headers</span><span class="p">[</span><span class="s1">'User-Agent'</span><span class="p">]</span> <span class="o">=</span> <span class="n">user_agent</span>
</pre></div>
</div>
<p>Your user agent will now look like:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">mypackage</span><span class="o">/</span><span class="mf">0.0</span><span class="o">.</span><span class="mi">1</span> <span class="n">requests</span><span class="o">/</span><span class="mf">2.7</span><span class="o">.</span><span class="mi">0</span> <span class="n">requests</span><span class="o">-</span><span class="n">toolbelt</span><span class="o">/</span><span class="mf">0.5</span><span class="o">.</span><span class="mi">0</span> <span class="n">CPython</span><span class="o">/</span><span class="mf">2.7</span><span class="o">.</span><span class="mi">10</span> <span class="n">Darwin</span><span class="o">/</span><span class="mf">13.0</span><span class="o">.</span><span class="mi">0</span>
</pre></div>
</div>
</div>
<div class="section" id="selecting-only-what-you-want">
<h2>Selecting Only What You Want<a class="headerlink" href="#selecting-only-what-you-want" title="Permalink to this headline">¶</a></h2>
<div class="versionadded">
<p><span class="versionmodified">New in version 0.8.0.</span></p>
</div>
<p>While most people will find the <code class="docutils literal"><span class="pre">user_agent</span></code> function sufficient for their
usage, others will want to control exactly what information is included in the
User-Agent. For those people, the
<a class="reference internal" href="#requests_toolbelt.utils.user_agent.UserAgentBuilder" title="requests_toolbelt.utils.user_agent.UserAgentBuilder"><code class="xref py py-class docutils literal"><span class="pre">UserAgentBuilder</span></code></a> is the correct
tool. This is the tool that the toolbelt uses inside of
<code class="xref py py-func docutils literal"><span class="pre">user_agent()</span></code>. For example, let’s say
you <em>only</em> want your package, its versions, and some extra information, in
that case you would do:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">requests</span>
<span class="kn">from</span> <span class="nn">requests_toolbelt.utils</span> <span class="kn">import</span> <span class="n">user_agent</span> <span class="k">as</span> <span class="n">ua</span>
<span class="n">s</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">Session</span><span class="p">()</span>
<span class="n">s</span><span class="o">.</span><span class="n">headers</span><span class="p">[</span><span class="s1">'User-Agent'</span><span class="p">]</span> <span class="o">=</span> <span class="n">ua</span><span class="o">.</span><span class="n">UserAgentBuilder</span><span class="p">(</span>
<span class="s1">'mypackage'</span><span class="p">,</span> <span class="s1">'0.0.1'</span><span class="p">,</span>
<span class="p">)</span><span class="o">.</span><span class="n">include_extras</span><span class="p">([</span>
<span class="p">(</span><span class="s1">'requests'</span><span class="p">,</span> <span class="n">requests</span><span class="o">.</span><span class="n">__version__</span><span class="p">),</span>
<span class="p">])</span><span class="o">.</span><span class="n">build</span><span class="p">()</span>
</pre></div>
</div>
<p>Your user agent will now look like:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">mypackage</span><span class="o">/</span><span class="mf">0.0</span><span class="o">.</span><span class="mi">1</span> <span class="n">requests</span><span class="o">/</span><span class="mf">2.7</span><span class="o">.</span><span class="mi">0</span>
</pre></div>
</div>
<p>You can also optionally include the Python version information and System
information the same way that our <code class="docutils literal"><span class="pre">user_agent</span></code> function does.</p>
<dl class="class">
<dt id="requests_toolbelt.utils.user_agent.UserAgentBuilder">
<em class="property">class </em><code class="descclassname">requests_toolbelt.utils.user_agent.</code><code class="descname">UserAgentBuilder</code><span class="sig-paren">(</span><em>name</em>, <em>version</em><span class="sig-paren">)</span><a class="headerlink" href="#requests_toolbelt.utils.user_agent.UserAgentBuilder" title="Permalink to this definition">¶</a></dt>
<dd><p>Class to provide a greater level of control than <code class="xref py py-func docutils literal"><span class="pre">user_agent()</span></code>.</p>
<p>This is used by <code class="xref py py-func docutils literal"><span class="pre">user_agent()</span></code> to build its User-Agent string.</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="n">user_agent_str</span> <span class="o">=</span> <span class="n">UserAgentBuilder</span><span class="p">(</span>
<span class="n">name</span><span class="o">=</span><span class="s1">'requests-toolbelt'</span><span class="p">,</span>
<span class="n">version</span><span class="o">=</span><span class="s1">'17.4.0'</span><span class="p">,</span>
<span class="p">)</span><span class="o">.</span><span class="n">include_implementation</span><span class="p">(</span>
<span class="p">)</span><span class="o">.</span><span class="n">include_system</span><span class="p">(</span>
<span class="p">)</span><span class="o">.</span><span class="n">include_extras</span><span class="p">([</span>
<span class="p">(</span><span class="s1">'requests'</span><span class="p">,</span> <span class="s1">'2.14.2'</span><span class="p">),</span>
<span class="p">(</span><span class="s1">'urllib3'</span><span class="p">,</span> <span class="s1">'1.21.2'</span><span class="p">),</span>
<span class="p">])</span><span class="o">.</span><span class="n">build</span><span class="p">()</span>
</pre></div>
</div>
<dl class="method">
<dt id="requests_toolbelt.utils.user_agent.UserAgentBuilder.build">
<code class="descname">build</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#requests_toolbelt.utils.user_agent.UserAgentBuilder.build" title="Permalink to this definition">¶</a></dt>
<dd><p>Finalize the User-Agent string.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Returns:</th><td class="field-body">Formatted User-Agent string.</td>
</tr>
<tr class="field-even field"><th class="field-name">Return type:</th><td class="field-body">str</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="requests_toolbelt.utils.user_agent.UserAgentBuilder.include_extras">
<code class="descname">include_extras</code><span class="sig-paren">(</span><em>extras</em><span class="sig-paren">)</span><a class="headerlink" href="#requests_toolbelt.utils.user_agent.UserAgentBuilder.include_extras" title="Permalink to this definition">¶</a></dt>
<dd><p>Include extra portions of the User-Agent.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>extras</strong> (<em>list</em>) – list of tuples of extra-name and extra-version</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="requests_toolbelt.utils.user_agent.UserAgentBuilder.include_implementation">
<code class="descname">include_implementation</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#requests_toolbelt.utils.user_agent.UserAgentBuilder.include_implementation" title="Permalink to this definition">¶</a></dt>
<dd><p>Append the implementation string to the user-agent string.</p>
<p>This adds the the information that you’re using CPython 2.7.13 to the
User-Agent.</p>
</dd></dl>
<dl class="method">
<dt id="requests_toolbelt.utils.user_agent.UserAgentBuilder.include_system">
<code class="descname">include_system</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#requests_toolbelt.utils.user_agent.UserAgentBuilder.include_system" title="Permalink to this definition">¶</a></dt>
<dd><p>Append the information about the Operating System.</p>
</dd></dl>
</dd></dl>
</div>
</div>
</div>
</div>
<footer>
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
<a href="uploading-data.html" class="btn btn-neutral float-left" title="Uploading Data" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left"></span> Previous</a>
</div>
<hr/>
<div role="contentinfo">
<p>
© Copyright 2015, Ian Cordasco, Cory Benfield
</p>
</div>
Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/rtfd/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script type="text/javascript">
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>