<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>String Encodings — Buildbot 0.8.5 documentation</title>
<link rel="stylesheet" href="../_static/agogo.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '0.8.5',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</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>
<link rel="shortcut icon" href="../_static/buildbot.ico"/>
<link rel="top" title="Buildbot 0.8.5 documentation" href="../index.html" />
<link rel="up" title="Buildbot Development" href="index.html" />
<link rel="next" title="Metrics" href="metrics.html" />
<link rel="prev" title="Master-Slave API" href="master-slave.html" />
</head>
<body>
<div class="header-wrapper">
<div class="header">
<p class="logo"><a href="../index.html">
<img class="logo" src="../_static/header-text-transparent.png" alt="Logo"/>
</a></p>
<div class="headertitle"><a
href="../index.html">Buildbot 0.8.5 documentation</a></div>
<div class="rel">
<a href="master-slave.html" title="Master-Slave API"
accesskey="P">previous</a> |
<a href="metrics.html" title="Metrics"
accesskey="N">next</a> |
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |
<a href="../genindex.html" title="General Index"
accesskey="I">index</a>
</div>
</div>
</div>
<div class="content-wrapper">
<div class="content">
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="string-encodings">
<h1>String Encodings<a class="headerlink" href="#string-encodings" title="Permalink to this headline">¶</a></h1>
<p>Buildbot expects all strings used internally to be valid Unicode strings - not
bytestrings.</p>
<p>Note that Buildbot rarely feeds strings back into external tools in such a way
that those strings must match. For example, Buildbot does not attempt to
access the filenames specified in a Change. So it is more important to store
strings in a manner that will be most useful to a human reader (e.g., in
logfiles, web status, etc.) than to store them in a lossless format.</p>
<div class="section" id="inputs">
<h2>Inputs<a class="headerlink" href="#inputs" title="Permalink to this headline">¶</a></h2>
<p>On input, strings should be decoded, if their encoding is known. Where
necessary, the assumed input encoding should be configurable. In some cases,
such as filenames, this encoding is not known or not well-defined (e.g., a
utf-8 encoded filename in a latin-1 directory). In these cases, the input
mechanisms should make a best effort at decoding, and use e.g., the
<tt class="docutils literal"><span class="pre">errors='replace'</span></tt> option to fail gracefully on un-decodable characters.</p>
</div>
<div class="section" id="outputs">
<h2>Outputs<a class="headerlink" href="#outputs" title="Permalink to this headline">¶</a></h2>
<p>At most points where Buildbot outputs a string, the target encoding is known.
For example, the web status can encode to utf-8. In cases where it is not
known, it should be configurable, with a safe fallback (e.g., ascii with
<tt class="docutils literal"><span class="pre">errors='replace'</span></tt>.
String Encodings
================</p>
<p>Buildbot expects all strings used internally to be valid Unicode strings - not
bytestrings.</p>
<p>Note that Buildbot rarely feeds strings back into external tools in such a way
that those strings must match. For example, Buildbot does not attempt to
access the filenames specified in a Change. So it is more important to store
strings in a manner that will be most useful to a human reader (e.g., in
logfiles, web status, etc.) than to store them in a lossless format.</p>
<div class="section" id="id1">
<h3>Inputs<a class="headerlink" href="#id1" title="Permalink to this headline">¶</a></h3>
<p>On input, strings should be decoded, if their encoding is known. Where
necessary, the assumed input encoding should be configurable. In some cases,
such as filenames, this encoding is not known or not well-defined (e.g., a
utf-8 encoded filename in a latin-1 directory, or a patch file). In these
cases, the input mechanisms should make a best effort at decoding, and use
e.g., the <tt class="docutils literal"><span class="pre">errors='replace'</span></tt> option to fail gracefully on un-decodable
characters.</p>
</div>
<div class="section" id="id2">
<h3>Outputs<a class="headerlink" href="#id2" title="Permalink to this headline">¶</a></h3>
<p>At most points where Buildbot outputs a string, the target encoding is known.
For example, the web status can encode to utf-8. In cases where it is not
known, it should be configurable, with a safe fallback (e.g., ascii with
<tt class="docutils literal"><span class="pre">errors='replace'</span></tt>.</p>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sidebar">
<h3>Table Of Contents</h3>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../tutorial/index.html">Buildbot Tutorial</a></li>
<li class="toctree-l1"><a class="reference internal" href="../manual/index.html">Buildbot Manual</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="index.html">Buildbot Development</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="style.html">Buildbot Coding Style</a></li>
<li class="toctree-l2"><a class="reference internal" href="master-overview.html">Master Organization</a></li>
<li class="toctree-l2"><a class="reference internal" href="config.html">Buildbot Configuration</a></li>
<li class="toctree-l2"><a class="reference internal" href="utils.html">Utilities</a></li>
<li class="toctree-l2"><a class="reference internal" href="database.html">The Buildbot Database</a></li>
<li class="toctree-l2"><a class="reference internal" href="results.html">Build Result Codes</a></li>
<li class="toctree-l2"><a class="reference internal" href="formats.html">File Formats</a></li>
<li class="toctree-l2"><a class="reference internal" href="webstatus.html">Web Status</a></li>
<li class="toctree-l2"><a class="reference internal" href="master-slave.html">Master-Slave API</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="">String Encodings</a><ul class="simple">
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="metrics.html">Metrics</a></li>
<li class="toctree-l2"><a class="reference internal" href="classes.html">Classes</a></li>
</ul>
</li>
</ul>
<h3 style="margin-top: 1.5em;">Search</h3>
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<div class="clearer"></div>
</div>
</div>
<div class="footer-wrapper">
<div class="footer">
<div class="left">
<a href="master-slave.html" title="Master-Slave API"
>previous</a> |
<a href="metrics.html" title="Metrics"
>next</a> |
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |
<a href="../genindex.html" title="General Index"
>index</a>
<br/>
<a href="../_sources/developer/encodings.txt"
rel="nofollow">Show Source</a>
</div>
<div class="right">
<div class="footer">
© Copyright Buildbot Team Members.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.
</div>
</div>
<div class="clearer"></div>
</div>
</div>
</body>
</html>
