Skip to content

Commit 2752937

Browse files
jswhit2jswhit2
jswhit2
authored and
jswhit2
committed
update docs with threading warning
1 parent 2ba0cbe commit 2752937

File tree

1 file changed

+34
-14
lines changed

1 file changed

+34
-14
lines changed

‎docs/index.html‎

Lines changed: 34 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -3,20 +3,31 @@
33
<head>
44
<meta charset="utf-8">
55
<meta name="viewport" content="width=device-width, initial-scale=1, minimum-scale=1">
6-
<meta name="generator" content="pdoc3 0.11.1">
6+
<meta name="generator" content="pdoc3 0.11.6">
77
<title>netCDF4 API documentation</title>
8-
<meta name="description" content="Version 1.7.2
8+
<meta name="description" content="Version 1.7.4
99
…">
1010
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/10up-sanitize.css/13.0.0/sanitize.min.css" integrity="sha512-y1dtMcuvtTMJc1yPgEqF0ZjQbhnc/bFhyvIyVNb9Zk5mIGtqVaAB1Ttl28su8AvFMOY0EwRbAe+HCLqj6W7/KA==" crossorigin>
1111
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/10up-sanitize.css/13.0.0/typography.min.css" integrity="sha512-Y1DYSb995BAfxobCkKepB1BqJJTPrOp3zPL74AWFugHHmmdcvO+C48WLrUOlhGMc0QG7AE3f7gmvvcrmX2fDoA==" crossorigin>
1212
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/styles/default.min.css" crossorigin>
13-
<style>:root{--highlight-color:#fe9}.flex{display:flex !important}body{line-height:1.5em}#content{padding:20px}#sidebar{padding:1.5em;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:2em 0 .50em 0}h3{font-size:1.4em;margin:1.6em 0 .7em 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 .2s ease-in-out}a:visited{color:#503}a:hover{color:#b62}.title code{font-weight:bold}h2[id^="header-"]{margin-top:2em}.ident{color:#900;font-weight:bold}pre code{font-size:.8em;line-height:1.4em;padding:1em;display:block}code{background:#f3f3f3;font-family:"DejaVu Sans Mono",monospace;padding:1px 4px;overflow-wrap:break-word}h1 code{background:transparent}pre{border-top:1px solid #ccc;border-bottom:1px solid #ccc;margin:1em 0}#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-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 1em;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>
13+
<style>:root{--highlight-color:#fe9}.flex{display:flex !important}body{line-height:1.5em}#content{padding:20px}#sidebar{padding:1.5em;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:2em 0 .50em 0}h3{font-size:1.4em;margin:1.6em 0 .7em 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 .2s ease-in-out}a:visited{color:#503}a:hover{color:#b62}.title code{font-weight:bold}h2[id^="header-"]{margin-top:2em}.ident{color:#900;font-weight:bold}pre code{font-size:.8em;line-height:1.4em;padding:1em;display:block}code{background:#f3f3f3;font-family:"DejaVu Sans Mono",monospace;padding:1px 4px;overflow-wrap:break-word}h1 code{background:transparent}pre{border-top:1px solid #ccc;border-bottom:1px solid #ccc;margin:1em 0}#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-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;min-width:max-content}.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 1em;margin:1em 0}.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>
1414
<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}.name{font-size:1em}main{display:flex;flex-direction:row-reverse;justify-content:flex-end}.toc ul ul,#index ul ul{padding-left:1em}.toc > ul > li{margin-top:.5em}}</style>
1515
<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>
1616
<script defer src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/highlight.min.js" integrity="sha512-D9gUyxqja7hBtkWpPWGt9wfbfaMGVt9gnyCvYa+jojwwPHLCzUm5i8rpk7vD7wNee9bA35eYIjobYPaQuKS1MQ==" crossorigin></script>
1717
<script>window.addEventListener('DOMContentLoaded', () => {
1818
hljs.configure({languages: ['bash', 'css', 'diff', 'graphql', 'ini', 'javascript', 'json', 'plaintext', 'python', 'python-repl', 'rust', 'shell', 'sql', 'typescript', 'xml', 'yaml']});
1919
hljs.highlightAll();
20+
/* Collapse source docstrings */
21+
setTimeout(() => {
22+
[...document.querySelectorAll('.hljs.language-python > .hljs-string')]
23+
.filter(el => el.innerHTML.length > 200 && ['"""', "'''"].includes(el.innerHTML.substring(0, 3)))
24+
.forEach(el => {
25+
let d = document.createElement('details');
26+
d.classList.add('hljs-string');
27+
d.innerHTML = '<summary>"""</summary>' + el.innerHTML.substring(3);
28+
el.replaceWith(d);
29+
});
30+
}, 100);
2031
})</script>
2132
</head>
2233
<body>
@@ -26,7 +37,7 @@
2637
<h1 class="title">Package <code>netCDF4</code></h1>
2738
</header>
2839
<section id="section-intro">
29-
<h2 id="version-172">Version 1.7.2</h2>
40+
<h2 id="version-174">Version 1.7.4</h2>
3041
<h1 id="introduction">Introduction</h1>
3142
<p>netcdf4-python is a Python interface to the netCDF C library.</p>
3243
<p><a href="http://www.unidata.ucar.edu/software/netcdf/">netCDF</a> version 4 has many features
@@ -1003,6 +1014,11 @@ <h2 id="parallel-io">Parallel IO</h2>
10031014
to write to it.</li>
10041015
<li>You cannot use variable-length (VLEN) data types.</li>
10051016
</ul>
1017+
<p><strong><em>Import warning regarding threads:</em></strong>
1018+
The underlying netcdf-c library is not thread-safe, so netcdf4-python cannot perform parallel
1019+
IO in a multi-threaded environment.
1020+
Users should expect segfaults if a netcdf file is opened on multiple threads - care should
1021+
be taken to restrict netcdf4-python usage to a single thread, even when using free-threaded python.</p>
10061022
<h2 id="dealing-with-strings">Dealing with strings</h2>
10071023
<p>The most flexible way to store arrays of strings is with the
10081024
<a href="#variable-length-vlen-data-type">Variable-length (vlen) string data type</a>. However, this requires
@@ -1018,7 +1034,7 @@ <h2 id="dealing-with-strings">Dealing with strings</h2>
10181034
(dtype <code>S1</code>) variable, the <code><a title="netCDF4.chartostring" href="#netCDF4.chartostring">chartostring()</a></code> utility function is used to convert the array of
10191035
characters to an array of strings with one less dimension (the last dimension is
10201036
interpreted as the length of each string) when reading the data. The character
1021-
set (usually ascii) is specified by the <code>_Encoding</code> attribute. If <code>_Encoding</code>
1037+
set is specified by the <code>_Encoding</code> attribute. If <code>_Encoding</code>
10221038
is 'none' or 'bytes', then the character array is converted to a numpy
10231039
fixed-width byte string array (dtype <code>S#</code>), otherwise a numpy unicode (dtype
10241040
<code>U#</code>) array is created.
@@ -1196,7 +1212,7 @@ <h2 id="support-for-complex-numbers">Support for complex numbers</h2>
11961212
<p>Support for complex numbers is handled via the
11971213
<a href="https://github.com/PlasmaFAIR/nc-complex"><code>nc-complex</code></a> library. See there for
11981214
further details.</p>
1199-
<p><strong>contact</strong>: Jeffrey Whitaker <a href="&#109;&#97;&#105;&#108;&#116;&#111;&#58;&#106;&#101;&#102;&#102;&#114;&#101;&#121;&#46;&#115;&#46;&#119;&#104;&#105;&#116;&#97;&#107;&#101;&#114;&#64;&#110;&#111;&#97;&#97;&#46;&#103;&#111;&#118;">&#106;&#101;&#102;&#102;&#114;&#101;&#121;&#46;&#115;&#46;&#119;&#104;&#105;&#116;&#97;&#107;&#101;&#114;&#64;&#110;&#111;&#97;&#97;&#46;&#103;&#111;&#118;</a></p>
1215+
<p><strong>contact</strong>: Jeffrey Whitaker <a href="&#109;&#97;&#105;&#108;&#116;&#111;&#58;&#119;&#104;&#105;&#116;&#97;&#107;&#101;&#114;&#46;&#106;&#101;&#102;&#102;&#114;&#101;&#121;&#64;&#103;&#109;&#97;&#105;&#108;&#46;&#99;&#111;&#109;">&#119;&#104;&#105;&#116;&#97;&#107;&#101;&#114;&#46;&#106;&#101;&#102;&#102;&#114;&#101;&#121;&#64;&#103;&#109;&#97;&#105;&#108;&#46;&#99;&#111;&#109;</a></p>
12001216
<p><strong>copyright</strong>: 2008 by Jeffrey Whitaker.</p>
12011217
<p><strong>license</strong>: Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:</p>
12021218
<p>The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.</p>
@@ -1229,7 +1245,7 @@ <h2 class="section-title" id="header-functions">Functions</h2>
12291245
<span>def <span class="ident">date2index</span></span>(<span>dates, nctime, calendar=None, select='exact', has_year_zero=None)</span>
12301246
</code></dt>
12311247
<dd>
1232-
<div class="desc"><p>date2index(dates, nctime, calendar=None, select=u'exact', has_year_zero=None)</p>
1248+
<div class="desc"><p>date2index(dates, nctime, calendar=None, select='exact', has_year_zero=None)</p>
12331249
<p>Return indices of a netCDF time variable corresponding to the given dates.</p>
12341250
<p><strong>dates</strong>: A datetime object or a sequence of datetime objects.
12351251
The datetime objects should not include a time-zone offset.</p>
@@ -1347,10 +1363,10 @@ <h2 class="section-title" id="header-functions">Functions</h2>
13471363
used to build the module, and when it was built.</p></div>
13481364
</dd>
13491365
<dt id="netCDF4.num2date"><code class="name flex">
1350-
<span>def <span class="ident">num2date</span></span>(<span>times, units, calendar='standard', only_use_cftime_datetimes=True, only_use_python_datetimes=False, has_year_zero=None)</span>
1366+
<span>def <span class="ident">num2date</span></span>(<span>times,<br>units,<br>calendar='standard',<br>only_use_cftime_datetimes=True,<br>only_use_python_datetimes=False,<br>has_year_zero=None)</span>
13511367
</code></dt>
13521368
<dd>
1353-
<div class="desc"><p>num2date(times, units, calendar=u'standard', only_use_cftime_datetimes=True, only_use_python_datetimes=False, has_year_zero=None)</p>
1369+
<div class="desc"><p>num2date(times, units, calendar='standard', only_use_cftime_datetimes=True, only_use_python_datetimes=False, has_year_zero=None)</p>
13541370
<p>Return datetime objects given numeric time values. The units
13551371
of the numeric time values are described by the <strong>units</strong> argument
13561372
and the <strong>calendar</strong> keyword. The returned datetime objects represent
@@ -1460,10 +1476,10 @@ <h2 class="section-title" id="header-functions">Functions</h2>
14601476
(default) or <code>'U1'</code> (if dtype=<code>'U'</code>)</p></div>
14611477
</dd>
14621478
<dt id="netCDF4.stringtochar"><code class="name flex">
1463-
<span>def <span class="ident">stringtochar</span></span>(<span>a, encoding='utf-8')</span>
1479+
<span>def <span class="ident">stringtochar</span></span>(<span>a, encoding='utf-8', n_strlen=None)</span>
14641480
</code></dt>
14651481
<dd>
1466-
<div class="desc"><p><strong><code>stringtochar(a,encoding='utf-8')</code></strong></p>
1482+
<div class="desc"><p><strong><code>stringtochar(a,encoding='utf-8',n_strlen=None)</code></strong></p>
14671483
<p>convert a string array to a character array with one extra dimension</p>
14681484
<p><strong><code>a</code></strong>:
14691485
Input numpy string array with numpy datatype <code>'SN'</code> or <code>'UN'</code>, where N
@@ -1473,6 +1489,10 @@ <h2 class="section-title" id="header-functions">Functions</h2>
14731489
<p>optional kwarg <code>encoding</code> can be used to specify character encoding (default
14741490
<code>utf-8</code>). If <code>encoding</code> is 'none' or 'bytes', a <code>numpy.string_</code> the input array
14751491
is treated a raw byte strings (<code>numpy.string_</code>).</p>
1492+
<p>optional kwarg <code>n_strlen</code> is the number of characters in each string.
1493+
Default
1494+
is None, which means <code>n_strlen</code> will be set to a.itemsize (the number of bytes
1495+
used to represent each string in the input array).</p>
14761496
<p>returns a numpy character array with datatype <code>'S1'</code> or <code>'U1'</code>
14771497
and shape <code>a.shape + (N,)</code>, where N is the length of each string in a.</p></div>
14781498
</dd>
@@ -1834,7 +1854,7 @@ <h3>Methods</h3>
18341854
datatype.</p></div>
18351855
</dd>
18361856
<dt id="netCDF4.Dataset.createVariable"><code class="name flex">
1837-
<span>def <span class="ident">createVariable</span></span>(<span>self, varname, datatype, dimensions=(), compression=None, zlib=False, complevel=4, shuffle=True, szip_coding='nn', szip_pixels_per_block=8, blosc_shuffle=1, fletcher32=False, contiguous=False, chunksizes=None, endian='native', least_significant_digit=None, significant_digits=None, quantize_mode='BitGroom', fill_value=None, chunk_cache=None)</span>
1857+
<span>def <span class="ident">createVariable</span></span>(<span>self,<br>varname,<br>datatype,<br>dimensions=(),<br>compression=None,<br>zlib=False,<br>complevel=4,<br>shuffle=True,<br>szip_coding='nn',<br>szip_pixels_per_block=8,<br>blosc_shuffle=1,<br>fletcher32=False,<br>contiguous=False,<br>chunksizes=None,<br>endian='native',<br>least_significant_digit=None,<br>significant_digits=None,<br>quantize_mode='BitGroom',<br>fill_value=None,<br>chunk_cache=None)</span>
18381858
</code></dt>
18391859
<dd>
18401860
<div class="desc"><p><strong><code>createVariable(self, varname, datatype, dimensions=(), compression=None, zlib=False,
@@ -3144,7 +3164,7 @@ <h3>Methods</h3>
31443164
<nav id="sidebar">
31453165
<div class="toc">
31463166
<ul>
3147-
<li><a href="#version-172">Version 1.7.2</a></li>
3167+
<li><a href="#version-174">Version 1.7.4</a></li>
31483168
<li><a href="#introduction">Introduction</a><ul>
31493169
<li><a href="#quick-install">Quick Install</a></li>
31503170
<li><a href="#developer-install">Developer Install</a></li>
@@ -3343,7 +3363,7 @@ <h4><code><a title="netCDF4.Variable" href="#netCDF4.Variable">Variable</a></cod
33433363
</nav>
33443364
</main>
33453365
<footer id="footer">
3346-
<p>Generated by <a href="https://pdoc3.github.io/pdoc" title="pdoc: Python API documentation generator"><cite>pdoc</cite> 0.11.1</a>.</p>
3366+
<p>Generated by <a href="https://pdoc3.github.io/pdoc" title="pdoc: Python API documentation generator"><cite>pdoc</cite> 0.11.6</a>.</p>
33473367
</footer>
33483368
</body>
33493369
</html>

0 commit comments

Comments
 (0)