docs/env.html
<!--
-- Copyright (C) 2020 Arm Mbed. All rights reserved.
-- SPDX-License-Identifier: Apache-2.0
-->
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1, minimum-scale=1" />
<meta name="generator" content="pdoc 0.8.4" />
<title>mbed_targets.env API documentation</title>
<meta name="description" content="Environment options for `mbed-targets` …" />
<link rel="preload stylesheet" as="style" href="https://cdnjs.cloudflare.com/ajax/libs/10up-sanitize.css/11.0.1/sanitize.min.css" integrity="sha256-PK9q560IAAa6WVRRh76LtCaI8pjTJ2z11v0miyNNjrs=" crossorigin>
<link rel="preload stylesheet" as="style" href="https://cdnjs.cloudflare.com/ajax/libs/10up-sanitize.css/11.0.1/typography.min.css" integrity="sha256-7l/o7C8jubJiy74VsKTidCy1yBkRtiUGbVkYBylBqUg=" crossorigin>
<link rel="stylesheet preload" as="style" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.18.1/styles/github.min.css" crossorigin>
<style>:root{--highlight-color:#fe9}.flex{display:flex !important}body{line-height:1.5em}#content{padding:20px}#sidebar{padding:30px;overflow:hidden}#sidebar > *:last-child{margin-bottom:2cm}.http-server-breadcrumbs{font-size:130%;margin:0 0 15px 0}#footer{font-size:.75em;padding:5px 30px;border-top:1px solid #ddd;text-align:right}#footer p{margin:0 0 0 1em;display:inline-block}#footer p:last-child{margin-right:30px}h1,h2,h3,h4,h5{font-weight:300}h1{font-size:2.5em;line-height:1.1em}h2{font-size:1.75em;margin:1em 0 .50em 0}h3{font-size:1.4em;margin:25px 0 10px 0}h4{margin:0;font-size:105%}h1:target,h2:target,h3:target,h4:target,h5:target,h6:target{background:var(--highlight-color);padding:.2em 0}a{color:#058;text-decoration:none;transition:color .3s ease-in-out}a:hover{color:#e82}.title code{font-weight:bold}h2[id^="header-"]{margin-top:2em}.ident{color:#900}pre code{background:#f8f8f8;font-size:.8em;line-height:1.4em}code{background:#f2f2f1;padding:1px 4px;overflow-wrap:break-word}h1 code{background:transparent}pre{background:#f8f8f8;border:0;border-top:1px solid #ccc;border-bottom:1px solid #ccc;margin:1em 0;padding:1ex}#http-server-module-list{display:flex;flex-flow:column}#http-server-module-list div{display:flex}#http-server-module-list dt{min-width:10%}#http-server-module-list p{margin-top:0}.toc ul,#index{list-style-type:none;margin:0;padding:0}#index code{background:transparent}#index h3{border-bottom:1px solid #ddd}#index ul{padding:0}#index h4{margin-top:.6em;font-weight:bold}@media (min-width:200ex){#index .two-column{column-count:2}}@media (min-width:300ex){#index .two-column{column-count:3}}dl{margin-bottom:2em}dl dl:last-child{margin-bottom:4em}dd{margin:0 0 1em 3em}#header-classes + dl > dd{margin-bottom:3em}dd dd{margin-left:2em}dd p{margin:10px 0}.name{background:#eee;font-weight:bold;font-size:.85em;padding:5px 10px;display:inline-block;min-width:40%}.name:hover{background:#e0e0e0}dt:target .name{background:var(--highlight-color)}.name > span:first-child{white-space:nowrap}.name.class > span:nth-child(2){margin-left:.4em}.inherited{color:#999;border-left:5px solid #eee;padding-left:1em}.inheritance em{font-style:normal;font-weight:bold}.desc h2{font-weight:400;font-size:1.25em}.desc h3{font-size:1em}.desc dt code{background:inherit}.source summary,.git-link-div{color:#666;text-align:right;font-weight:400;font-size:.8em;text-transform:uppercase}.source summary > *{white-space:nowrap;cursor:pointer}.git-link{color:inherit;margin-left:1em}.source pre{max-height:500px;overflow:auto;margin:0}.source pre code{font-size:12px;overflow:visible}.hlist{list-style:none}.hlist li{display:inline}.hlist li:after{content:',\2002'}.hlist li:last-child:after{content:none}.hlist .hlist{display:inline;padding-left:1em}img{max-width:100%}td{padding:0 .5em}.admonition{padding:.1em .5em;margin-bottom:1em}.admonition-title{font-weight:bold}.admonition.note,.admonition.info,.admonition.important{background:#aef}.admonition.todo,.admonition.versionadded,.admonition.tip,.admonition.hint{background:#dfd}.admonition.warning,.admonition.versionchanged,.admonition.deprecated{background:#fd4}.admonition.error,.admonition.danger,.admonition.caution{background:lightpink}</style>
<style media="screen and (min-width: 700px)">@media screen and (min-width:700px){#sidebar{width:30%;height:100vh;overflow:auto;position:sticky;top:0}#content{width:70%;max-width:100ch;padding:3em 4em;border-left:1px solid #ddd}pre code{font-size:1em}.item .name{font-size:1em}main{display:flex;flex-direction:row-reverse;justify-content:flex-end}.toc ul ul,#index ul{padding-left:1.5em}.toc > ul > li{margin-top:.5em}}</style>
<style media="print">@media print{#sidebar h1{page-break-before:always}.source{display:none}}@media print{*{background:transparent !important;color:#000 !important;box-shadow:none !important;text-shadow:none !important}a[href]:after{content:" (" attr(href) ")";font-size:90%}a[href][title]:after{content:none}abbr[title]:after{content:" (" attr(title) ")"}.ir a:after,a[href^="javascript:"]:after,a[href^="#"]:after{content:""}pre,blockquote{border:1px solid #999;page-break-inside:avoid}thead{display:table-header-group}tr,img{page-break-inside:avoid}img{max-width:100% !important}@page{margin:0.5cm}p,h2,h3{orphans:3;widows:3}h1,h2,h3,h4,h5,h6{page-break-after:avoid}}</style>
<script defer src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.18.1/highlight.min.js" integrity="sha256-eOgo0OtLL4cdq7RdwRUiGKLX9XsIJ7nGhWEKbohmVAQ=" crossorigin></script>
<script>window.addEventListener('DOMContentLoaded', () => hljs.initHighlighting())</script>
</head>
<body>
<main>
<article id="content">
<header>
<h1 class="title">Module <code>mbed_targets.env</code></h1>
</header>
<section id="section-intro">
<p>Environment options for <code>mbed-targets</code>.</p>
<p>All the env configuration options can be set either via environment variables or using a <code>.<a title="mbed_targets.env.env" href="#mbed_targets.env.env">env</a></code> file
containing the variable definitions as follows:</p>
<pre><code>VARIABLE=value
</code></pre>
<p>Environment variables take precendence, meaning the values set in the file will be overriden
by any values previously set in your environment.</p>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>Do not upload <code>.<a title="mbed_targets.env.env" href="#mbed_targets.env.env">env</a></code> files containing private tokens to version control! If you use this package
as a dependency of your project, please ensure to include the <code>.<a title="mbed_targets.env.env" href="#mbed_targets.env.env">env</a></code> in your <code>.gitignore</code>.</p>
</div>
<details class="source">
<summary>
<span>Expand source code</span>
</summary>
<pre><code class="python">#
# Copyright (C) 2020 Arm Mbed. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
#
"""Environment options for `mbed-targets`.
All the env configuration options can be set either via environment variables or using a `.env` file
containing the variable definitions as follows:
```
VARIABLE=value
```
Environment variables take precendence, meaning the values set in the file will be overriden
by any values previously set in your environment.
.. WARNING::
Do not upload `.env` files containing private tokens to version control! If you use this package
as a dependency of your project, please ensure to include the `.env` in your `.gitignore`.
"""
import os
import dotenv
dotenv.load_dotenv(dotenv.find_dotenv(usecwd=True))
class Env:
"""Provides access to environment variables.
Ensures variables are reloaded when environment changes during runtime.
Additionally allows to expose documented instance variables in pdoc
generated output.
"""
@property
def MBED_API_AUTH_TOKEN(self) -> str:
"""Token to use when accessing online API.
Mbed Targets uses the online mbed board database at os.mbed.com as its data source.
A snapshot of the board database is shipped with the package, for faster lookup of known
boards. Only public boards are stored in the database snapshot. If you are fetching data
for a private board, mbed-targets will need to contact the online database.
To fetch data about private boards from the online database, the user must have an account
on os.mbed.com and be member of a vendor team that has permissions to see the private board.
An authentication token for the team member must be provided in an environment variable named
`MBED_API_AUTH_TOKEN`.
"""
return os.getenv("MBED_API_AUTH_TOKEN", "")
@property
def MBED_DATABASE_MODE(self) -> str:
"""Database mode to use when retrieving board data.
Mbed Targets supports an online and offline mode, which controls where to look up the board database.
The board lookup can be from either the online or offline database, depending
on the value of an environment variable called `MBED_DATABASE_MODE`.
The mode can be set to one of the following:
- `AUTO`: the offline database is searched first, if the board isn't found the online database is searched.
- `ONLINE`: the online database is always used.
- `OFFLINE`: the offline database is always used.
If `MBED_DATABASE_MODE` is not set, it defaults to `AUTO`.
"""
return os.getenv("MBED_DATABASE_MODE", "AUTO")
env = Env()
"""Instance of `Env` class."""</code></pre>
</details>
</section>
<section>
</section>
<section>
<h2 class="section-title" id="header-variables">Global variables</h2>
<dl>
<dt id="mbed_targets.env.env"><code class="name">var <span class="ident">env</span></code></dt>
<dd>
<div class="desc"><p>Instance of <code><a title="mbed_targets.env.Env" href="#mbed_targets.env.Env">Env</a></code> class.</p></div>
</dd>
</dl>
</section>
<section>
</section>
<section>
<h2 class="section-title" id="header-classes">Classes</h2>
<dl>
<dt id="mbed_targets.env.Env"><code class="flex name class">
<span>class <span class="ident">Env</span></span>
</code></dt>
<dd>
<div class="desc"><p>Provides access to environment variables.</p>
<p>Ensures variables are reloaded when environment changes during runtime.
Additionally allows to expose documented instance variables in pdoc
generated output.</p></div>
<details class="source">
<summary>
<span>Expand source code</span>
</summary>
<pre><code class="python">class Env:
"""Provides access to environment variables.
Ensures variables are reloaded when environment changes during runtime.
Additionally allows to expose documented instance variables in pdoc
generated output.
"""
@property
def MBED_API_AUTH_TOKEN(self) -> str:
"""Token to use when accessing online API.
Mbed Targets uses the online mbed board database at os.mbed.com as its data source.
A snapshot of the board database is shipped with the package, for faster lookup of known
boards. Only public boards are stored in the database snapshot. If you are fetching data
for a private board, mbed-targets will need to contact the online database.
To fetch data about private boards from the online database, the user must have an account
on os.mbed.com and be member of a vendor team that has permissions to see the private board.
An authentication token for the team member must be provided in an environment variable named
`MBED_API_AUTH_TOKEN`.
"""
return os.getenv("MBED_API_AUTH_TOKEN", "")
@property
def MBED_DATABASE_MODE(self) -> str:
"""Database mode to use when retrieving board data.
Mbed Targets supports an online and offline mode, which controls where to look up the board database.
The board lookup can be from either the online or offline database, depending
on the value of an environment variable called `MBED_DATABASE_MODE`.
The mode can be set to one of the following:
- `AUTO`: the offline database is searched first, if the board isn't found the online database is searched.
- `ONLINE`: the online database is always used.
- `OFFLINE`: the offline database is always used.
If `MBED_DATABASE_MODE` is not set, it defaults to `AUTO`.
"""
return os.getenv("MBED_DATABASE_MODE", "AUTO")</code></pre>
</details>
<h3>Instance variables</h3>
<dl>
<dt id="mbed_targets.env.Env.MBED_API_AUTH_TOKEN"><code class="name">var <span class="ident">MBED_API_AUTH_TOKEN</span> : str</code></dt>
<dd>
<div class="desc"><p>Token to use when accessing online API.</p>
<p>Mbed Targets uses the online mbed board database at os.mbed.com as its data source.
A snapshot of the board database is shipped with the package, for faster lookup of known
boards. Only public boards are stored in the database snapshot. If you are fetching data
for a private board, mbed-targets will need to contact the online database.</p>
<p>To fetch data about private boards from the online database, the user must have an account
on os.mbed.com and be member of a vendor team that has permissions to see the private board.
An authentication token for the team member must be provided in an environment variable named
<code>MBED_API_AUTH_TOKEN</code>.</p></div>
<details class="source">
<summary>
<span>Expand source code</span>
</summary>
<pre><code class="python">@property
def MBED_API_AUTH_TOKEN(self) -> str:
"""Token to use when accessing online API.
Mbed Targets uses the online mbed board database at os.mbed.com as its data source.
A snapshot of the board database is shipped with the package, for faster lookup of known
boards. Only public boards are stored in the database snapshot. If you are fetching data
for a private board, mbed-targets will need to contact the online database.
To fetch data about private boards from the online database, the user must have an account
on os.mbed.com and be member of a vendor team that has permissions to see the private board.
An authentication token for the team member must be provided in an environment variable named
`MBED_API_AUTH_TOKEN`.
"""
return os.getenv("MBED_API_AUTH_TOKEN", "")</code></pre>
</details>
</dd>
<dt id="mbed_targets.env.Env.MBED_DATABASE_MODE"><code class="name">var <span class="ident">MBED_DATABASE_MODE</span> : str</code></dt>
<dd>
<div class="desc"><p>Database mode to use when retrieving board data.</p>
<p>Mbed Targets supports an online and offline mode, which controls where to look up the board database.</p>
<p>The board lookup can be from either the online or offline database, depending
on the value of an environment variable called <code>MBED_DATABASE_MODE</code>.</p>
<p>The mode can be set to one of the following:</p>
<ul>
<li><code>AUTO</code>: the offline database is searched first, if the board isn't found the online database is searched.</li>
<li><code>ONLINE</code>: the online database is always used.</li>
<li><code>OFFLINE</code>: the offline database is always used.</li>
</ul>
<p>If <code>MBED_DATABASE_MODE</code> is not set, it defaults to <code>AUTO</code>.</p></div>
<details class="source">
<summary>
<span>Expand source code</span>
</summary>
<pre><code class="python">@property
def MBED_DATABASE_MODE(self) -> str:
"""Database mode to use when retrieving board data.
Mbed Targets supports an online and offline mode, which controls where to look up the board database.
The board lookup can be from either the online or offline database, depending
on the value of an environment variable called `MBED_DATABASE_MODE`.
The mode can be set to one of the following:
- `AUTO`: the offline database is searched first, if the board isn't found the online database is searched.
- `ONLINE`: the online database is always used.
- `OFFLINE`: the offline database is always used.
If `MBED_DATABASE_MODE` is not set, it defaults to `AUTO`.
"""
return os.getenv("MBED_DATABASE_MODE", "AUTO")</code></pre>
</details>
</dd>
</dl>
</dd>
</dl>
</section>
</article>
<nav id="sidebar">
<h1>Index</h1>
<div class="toc">
<ul></ul>
</div>
<ul id="index">
<li><h3>Super-module</h3>
<ul>
<li><code><a title="mbed_targets" href="index.html">mbed_targets</a></code></li>
</ul>
</li>
<li><h3><a href="#header-variables">Global variables</a></h3>
<ul class="">
<li><code><a title="mbed_targets.env.env" href="#mbed_targets.env.env">env</a></code></li>
</ul>
</li>
<li><h3><a href="#header-classes">Classes</a></h3>
<ul>
<li>
<h4><code><a title="mbed_targets.env.Env" href="#mbed_targets.env.Env">Env</a></code></h4>
<ul class="">
<li><code><a title="mbed_targets.env.Env.MBED_API_AUTH_TOKEN" href="#mbed_targets.env.Env.MBED_API_AUTH_TOKEN">MBED_API_AUTH_TOKEN</a></code></li>
<li><code><a title="mbed_targets.env.Env.MBED_DATABASE_MODE" href="#mbed_targets.env.Env.MBED_DATABASE_MODE">MBED_DATABASE_MODE</a></code></li>
</ul>
</li>
</ul>
</li>
</ul>
</nav>
</main>
<footer id="footer">
<p>Generated by <a href="https://pdoc3.github.io/pdoc"><cite>pdoc</cite> 0.8.4</a>.</p>
</footer>
</body>
</html>