matplotlib.github.com/1.4.0/devel/coding_guide.html at main · matplotlib/matplotlib.github.com

History

467 lines (439 loc) · 32.5 KB

Raw

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

134

135

136

137

138

139

140

141

142

143

144

145

146

147

148

149

150

151

152

153

154

155

156

157

158

159

160

161

162

163

164

165

166

167

168

169

170

171

172

173

174

175

176

177

178

179

180

181

182

183

184

185

186

187

188

189

190

191

192

193

194

195

196

197

198

199

200

201

202

203

204

205

206

207

208

209

210

211

212

213

214

215

216

217

218

219

220

221

222

223

224

225

226

227

228

229

230

231

232

233

234

235

236

237

238

239

240

241

242

243

244

245

246

247

248

249

250

251

252

253

254

255

256

257

258

259

260

261

262

263

264

265

266

267

268

269

270

271

272

273

274

275

276

277

278

279

280

281

282

283

284

285

286

287

288

289

290

291

292

293

294

295

296

297

298

299

300

301

302

303

304

305

306

307

308

309

310

311

312

313

314

315

316

317

318

319

320

321

322

323

324

325

326

327

328

329

330

331

332

333

334

335

336

337

338

339

340

341

342

343

344

345

346

347

348

349

350

351

352

353

354

355

356

357

358

359

360

361

362

363

364

365

366

367

368

369

370

371

372

373

374

375

376

377

378

379

380

381

382

383

384

385

386

387

388

389

390

391

392

393

394

395

396

397

398

399

400

401

402

403

404

405

406

407

408

409

410

411

412

413

414

415

416

417

418

419

420

421

422

423

424

425

426

427

428

429

430

431

432

433

434

435

436

437

438

439

440

441

442

443

444

445

446

447

448

449

450

451

452

453

454

455

456

457

458

459

460

461

462

463

464

465

466

467

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"

"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<head>

<title>Coding guide — Matplotlib 1.4.0 documentation</title>

type="text/css" />

type="text/css" />

var DOCUMENTATION_OPTIONS = {

URL_ROOT: '../',

VERSION: '1.4.0',

COLLAPSE_INDEX: false,

FILE_SUFFIX: '.html',

HAS_SOURCE: true

};

</script>

title="Search within Matplotlib 1.4.0 documentation"

href="../_static/opensearch.xml"/>

</head>

<body>

<div id="unreleased-message"> You are reading an old version of the documentation (v1.4.0). For the latest version see <a href="https://matplotlib.org/stable/devel/coding_guide.html">https://matplotlib.org/stable/devel/coding_guide.html</a></div>

</map>

</div>

<h3>Navigation</h3>

<ul>

<a href="../genindex.html" title="General Index"

accesskey="I">index</a></li>

<a href="../py-modindex.html" title="Python Module Index"

>modules</a> |</li>

<a href="portable_code.html" title="Writing code for Python 2 and 3"

accesskey="N">next</a> |</li>

<a href="index.html" title="The Matplotlib Developers’ Guide"

accesskey="P">previous</a> |</li>

<li><a href="../examples/index.html">examples</a>| </li>

<li><a href="../gallery.html">gallery</a>| </li>

<li><a href="../api/pyplot_summary.html">pyplot</a>| </li>

<li><a href="index.html" accesskey="U">The Matplotlib Developers’ Guide</a> »</li>

</ul>

</div>

<h3><a href="../contents.html">Table Of Contents</a></h3>

<ul>

<li><a class="reference internal" href="#">Coding guide</a><ul>

<li><a class="reference internal" href="#pull-request-checklist">Pull request checklist</a><ul>

<li><a class="reference internal" href="#branch-selection">Branch selection</a></li>

<li><a class="reference internal" href="#style">Style</a></li>

<li><a class="reference internal" href="#documentation">Documentation</a></li>

<li><a class="reference internal" href="#testing">Testing</a></li>

<li><a class="reference internal" href="#installation">Installation</a></li>

<li><a class="reference internal" href="#c-c-extensions">C/C++ extensions</a></li>

</ul>

</li>

<li><a class="reference internal" href="#style-guide">Style guide</a><ul>

<li><a class="reference internal" href="#keyword-argument-processing">Keyword argument processing</a></li>

</ul>

</li>

<li><a class="reference internal" href="#hints">Hints</a><ul>

<li><a class="reference internal" href="#developing-a-new-backend">Developing a new backend</a></li>

<li><a class="reference internal" href="#writing-examples">Writing examples</a></li>

<li><a class="reference internal" href="#writing-a-new-pyplot-function">Writing a new pyplot function</a></li>

</ul>

</li>

</ul>

</li>

</ul>

<h4>Previous topic</h4>

<a href="index.html"

title="previous chapter">The Matplotlib Developers’ Guide</a>

<h4>Next topic</h4>

<a href="portable_code.html"

title="next chapter">Writing code for Python 2 and 3</a>

<li><a href="../_sources/devel/coding_guide.txt"

rel="nofollow">Show Source</a></li>

</ul>

</div>

<h3>Quick search</h3>

</form>

Enter search terms or a module, class or function name.

</div>

</div>

<h1>Coding guide<a class="headerlink" href="#coding-guide" title="Permalink to this headline">¶</a></h1>

<h2>Pull request checklist<a class="headerlink" href="#pull-request-checklist" title="Permalink to this headline">¶</a></h2>

This checklist should be consulted when creating pull requests to make

sure they are complete before merging. These are not intended to be

rigidly followed—it’s just an attempt to list in one place all of

the items that are necessary for a good pull request. Of course, some

items will not always apply.

<h3>Branch selection<a class="headerlink" href="#branch-selection" title="Permalink to this headline">¶</a></h3>

<li>In general, simple bugfixes that are unlikely to introduce new bugs

of their own should be merged onto the maintenance branch. New

features, or anything that changes the API, should be made against

master. The rules are fuzzy here – when in doubt, try to get some

consensus.<ul>

<li>Once changes are merged into the maintenance branch, they should

be merged into master.</li>

</ul>

</li>

</ul>

</div>

<h3>Style<a class="headerlink" href="#style" title="Permalink to this headline">¶</a></h3>

<ul>

<li>Formatting should follow <a class="reference external" href="http://www.python.org/dev/peps/pep-0008/">PEP8</a>. Exceptions to these

rules are acceptable if it makes the code objectively more readable.

<li>You should consider installing/enabling automatic PEP8 checking in your

editor. Part of the test suite is checking PEP8 compliance, things

go smoother if the code is mostly PEP8 compliant to begin with.</li>

</ul>

</li>

<li>No tabs (only spaces). No trailing whitespace.

<li>Configuring your editor to remove these things upon saving will

save a lot of trouble.</li>

</ul>

</li>

<li>Import the following modules using the standard scipy conventions:

<div class="highlight-python"><div class="highlight"><pre>import numpy as np

import numpy.ma as ma

import matplotlib as mpl

from matplotlib import pyplot as plt

import matplotlib.cbook as cbook

import matplotlib.collections as mcol

import matplotlib.patches as mpatches

</pre></div>

</div>

</li>

<li>See below for additional points about

<a class="reference internal" href="#keyword-argument-processing">Keyword argument processing</a>, if code in your pull request

does that.

</li>

<li>Adding a new pyplot function involves generating code. See

<a class="reference internal" href="#new-pyplot-function">Writing a new pyplot function</a> for more information.

</li>

</ul>

</div>

<h3>Documentation<a class="headerlink" href="#documentation" title="Permalink to this headline">¶</a></h3>

<ul>

<li>Every new feature should be documented. If it’s a new module, don’t

forget to add a new rst file to the API docs.

</li>

<li>Docstrings should be in <a class="reference external" href="https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt">numpydoc format</a>.

Don’t be thrown off by the fact that many of the existing docstrings

are not in that format; we are working to standardize on

<tt class="xref py py-obj docutils literal">numpydoc</tt>.

Docstrings should look like (at a minimum):

<div class="highlight-python"><div class="highlight"><pre>def foo(bar, baz=None):

"""

This is a prose description of foo and all the great

things it does.

Parameters

----------

bar : (type of bar)

A description of bar

baz : (type of baz), optional

A description of baz

Returns

-------

foobar : (type of foobar)

A description of foobar

foobaz : (type of foobaz)

A description of foobaz

"""

# some very clever code

return foobar, foobaz

</pre></div>

</div>

</li>

<li>Each high-level plotting function should have a simple example in

the <tt class="xref py py-obj docutils literal">Example</tt> section of the docstring. This should be as simple as

possible to demonstrate the method. More complex examples should go

in the <tt class="xref py py-obj docutils literal">examples</tt> tree.

</li>

<li>Build the docs and make sure all formatting warnings are addressed.

</li>

<li>See <a class="reference internal" href="documenting_mpl.html#documenting-matplotlib">Documenting matplotlib</a> for our documentation style guide.

</li>

<li>If your changes are non-trivial, please make an entry in the

<tt class="file docutils literal">CHANGELOG</tt>.

</li>

<li>If your change is a major new feature, add an entry to

<tt class="file docutils literal">doc/users/whats_new.rst</tt>.

</li>

<li>If you change the API in a backward-incompatible way, please

document it in <tt class="file docutils literal">doc/api/api_changes.rst</tt>.

</li>

</ul>

</div>

<h3>Testing<a class="headerlink" href="#testing" title="Permalink to this headline">¶</a></h3>

Using the test framework is discussed in detail in the section

<a class="reference internal" href="testing.html#testing">Testing</a>.

<li>If the PR is a bugfix, add a test that fails prior to the change and

passes with the change. Include any relevant issue numbers in the

docstring of the test.</li>

<li>If this is a new feature, add a test that exercises as much of the

new feature as possible. (The <tt class="xref py py-obj docutils literal">--with-coverage</tt> option may be

useful here).</li>

<li>Make sure the Travis tests are passing before merging.<ul>

<li>The Travis tests automatically test on all of the Python versions

matplotlib supports whenever a pull request is created or updated.

The <tt class="xref py py-obj docutils literal">tox</tt> support in matplotlib may be useful for testing locally.</li>

</ul>

</li>

</ul>

</div>

<h3>Installation<a class="headerlink" href="#installation" title="Permalink to this headline">¶</a></h3>

<li>If you have added new files or directories, or reorganized existing

ones, make sure the new files included in the match patterns in

<tt class="file docutils literal">MANIFEST.in</tt>, and/or in <tt class="xref py py-obj docutils literal">package_data</tt> in <tt class="xref py py-obj docutils literal">setup.py</tt>.</li>

</ul>

</div>

<h3>C/C++ extensions<a class="headerlink" href="#c-c-extensions" title="Permalink to this headline">¶</a></h3>

<li>Extensions may be written in C or C++.</li>

<li>Code style should conform to PEP7 (understanding that PEP7 doesn’t

address C++, but most of its admonitions still apply).</li>

<li>Interfacing with Python may be done either with the raw Python/C API

or Cython. Use of PyCXX is discouraged for new code.</li>

<li>Python/C interface code should be kept separate from the core C/C++

code. The interface code should be named <tt class="xref py py-obj docutils literal">FOO_wrap.cpp</tt>.</li>

<li>Header file documentation (aka docstrings) should be in Numpydoc

format. We don’t plan on using automated tools for these

docstrings, and the Numpydoc format is well understood in the

scientific Python community.</li>

</ul>

</div>

<h2>Style guide<a class="headerlink" href="#style-guide" title="Permalink to this headline">¶</a></h2>

<h3>Keyword argument processing<a class="headerlink" href="#keyword-argument-processing" title="Permalink to this headline">¶</a></h3>

Matplotlib makes extensive use of <tt class="docutils literal">**kwargs</tt> for pass-through

customizations from one function to another. A typical example is in

<tt class="xref py py-func docutils literal">matplotlib.pylab.text()</tt>. The definition of the pylab text

function is a simple pass-through to

<a class="reference internal" href="../api/axes_api.html#matplotlib.axes.Axes.text" title="matplotlib.axes.Axes.text"><tt class="xref py py-meth docutils literal">matplotlib.axes.Axes.text()</tt></a>:

<div class="highlight-python"><div class="highlight"><pre># in pylab.py

def text(*args, **kwargs):

ret = gca().text(*args, **kwargs)

draw_if_interactive()

return ret

</pre></div>

</div>

<a class="reference internal" href="../api/axes_api.html#matplotlib.axes.Axes.text" title="matplotlib.axes.Axes.text"><tt class="xref py py-meth docutils literal">text()</tt></a> in simplified form looks like this,

i.e., it just passes all <tt class="docutils literal">args</tt> and <tt class="docutils literal">kwargs</tt> on to

<tt class="xref py py-meth docutils literal">matplotlib.text.Text.__init__()</tt>:

<div class="highlight-python"><div class="highlight"><pre># in axes.py

def text(self, x, y, s, fontdict=None, withdash=False, **kwargs):

t = Text(x=x, y=y, text=s, **kwargs)

</pre></div>

</div>

and <tt class="xref py py-meth docutils literal">__init__()</tt> (again with liberties for

illustration) just passes them on to the

<a class="reference internal" href="../api/artist_api.html#matplotlib.artist.Artist.update" title="matplotlib.artist.Artist.update"><tt class="xref py py-meth docutils literal">matplotlib.artist.Artist.update()</tt></a> method:

<div class="highlight-python"><div class="highlight"><pre># in text.py

def __init__(self, x=0, y=0, text='', **kwargs):

Artist.__init__(self)

self.update(kwargs)

</pre></div>

</div>

<tt class="docutils literal">update</tt> does the work looking for methods named like

<tt class="docutils literal">set_property</tt> if <tt class="docutils literal">property</tt> is a keyword argument. I.e., no one

looks at the keywords, they just get passed through the API to the

artist constructor which looks for suitably named methods and calls

them with the value.

As a general rule, the use of <tt class="docutils literal">**kwargs</tt> should be reserved for

pass-through keyword arguments, as in the example above. If all the

keyword args are to be used in the function, and not passed

on, use the key/value keyword args in the function definition rather

than the <tt class="docutils literal">**kwargs</tt> idiom.

In some cases, you may want to consume some keys in the local

function, and let others pass through. You can <tt class="docutils literal">pop</tt> the ones to be

used locally and pass on the rest. For example, in

<a class="reference internal" href="../api/axes_api.html#matplotlib.axes.Axes.plot" title="matplotlib.axes.Axes.plot"><tt class="xref py py-meth docutils literal">plot()</tt></a>, <tt class="docutils literal">scalex</tt> and <tt class="docutils literal">scaley</tt> are

local arguments and the rest are passed on as

<a class="reference internal" href="../api/lines_api.html#matplotlib.lines.Line2D" title="matplotlib.lines.Line2D"><tt class="xref py py-meth docutils literal">Line2D()</tt></a> keyword arguments:

<div class="highlight-python"><div class="highlight"><pre># in axes.py

def plot(self, *args, **kwargs):

scalex = kwargs.pop('scalex', True)

scaley = kwargs.pop('scaley', True)

if not self._hold: self.cla()

lines = []

for line in self._get_lines(*args, **kwargs):

self.add_line(line)

lines.append(line)

</pre></div>

</div>

Note: there is a use case when <tt class="docutils literal">kwargs</tt> are meant to be used locally

in the function (not passed on), but you still need the <tt class="docutils literal">**kwargs</tt>

idiom. That is when you want to use <tt class="docutils literal">*args</tt> to allow variable

numbers of non-keyword args. In this case, python will not allow you

to use named keyword args after the <tt class="docutils literal">*args</tt> usage, so you will be

forced to use <tt class="docutils literal">**kwargs</tt>. An example is

<tt class="xref py py-meth docutils literal">matplotlib.contour.ContourLabeler.clabel()</tt>:

<div class="highlight-python"><div class="highlight"><pre># in contour.py

def clabel(self, *args, **kwargs):

fontsize = kwargs.get('fontsize', None)

inline = kwargs.get('inline', 1)

self.fmt = kwargs.get('fmt', '%1.3f')

colors = kwargs.get('colors', None)

if len(args) == 0:

levels = self.levels

indices = range(len(self.levels))

elif len(args) == 1:

...etc...

</pre></div>

</div>

<h2>Hints<a class="headerlink" href="#hints" title="Permalink to this headline">¶</a></h2>

This section describes how to add certain kinds of new features to

matplotlib.

<h3>Developing a new backend<a class="headerlink" href="#developing-a-new-backend" title="Permalink to this headline">¶</a></h3>

If you are working on a custom backend, the backend setting in

<tt class="file docutils literal">matplotlibrc</tt> (<a class="reference internal" href="../users/customizing.html#customizing-matplotlib">Customizing matplotlib</a>) supports an

external backend via the <tt class="docutils literal">module</tt> directive. if

<tt class="file docutils literal">my_backend.py</tt> is a matplotlib backend in your

<a class="reference internal" href="../faq/environment_variables_faq.html#envvar-PYTHONPATH"><tt class="xref std std-envvar docutils literal">PYTHONPATH</tt></a>, you can set use it on one of several ways

<ul>

<li>in matplotlibrc:

<div class="highlight-python"><div class="highlight"><pre>backend : module://my_backend

</pre></div>

</div>

</li>

<li>with the use directive is your script:

<div class="highlight-python"><div class="highlight"><pre>import matplotlib

matplotlib.use('module://my_backend')

</pre></div>

</div>

</li>

<li>from the command shell with the -d flag:

<div class="highlight-python"><div class="highlight"><pre>> python simple_plot.py -d module://my_backend

</pre></div>

</div>

</li>

</ul>

</div>

<h3>Writing examples<a class="headerlink" href="#writing-examples" title="Permalink to this headline">¶</a></h3>

We have hundreds of examples in subdirectories of

<tt class="file docutils literal">matplotlib/examples</tt>, and these are automatically generated

when the website is built to show up both in the <a class="reference external" href="../examples/index.html">examples</a> and <a class="reference external" href="../gallery.html">gallery</a> sections of the website.

Any sample data that the example uses should be kept small and

distributed with matplotlib in the

<tt class="xref py py-obj docutils literal">lib/matplotlib/mpl-data/sample_data/</tt> directory. Then in your

example code you can load it into a file handle with:

<div class="highlight-python"><div class="highlight"><pre>import matplotlib.cbook as cbook

fh = cbook.get_sample_data('mydata.dat')

</pre></div>

</div>

<h3>Writing a new pyplot function<a class="headerlink" href="#writing-a-new-pyplot-function" title="Permalink to this headline">¶</a></h3>

A large portion of the pyplot interface is automatically generated by the

<tt class="xref py py-obj docutils literal">boilerplate.py</tt> script (in the root of the source tree). To add or remove

a plotting method from pyplot, edit the appropriate list in <tt class="xref py py-obj docutils literal">boilerplate.py</tt>

and then run the script which will update the content in

<tt class="xref py py-obj docutils literal">lib/matplotlib/pyplot.py</tt>. Both the changes in <tt class="xref py py-obj docutils literal">boilerplate.py</tt> and

<tt class="xref py py-obj docutils literal">lib/matplotlib/pyplot.py</tt> should be checked into the repository.

Note: boilerplate.py looks for changes in the installed version of matplotlib

and not the source tree. If you expect the pyplot.py file to show your new

changes, but they are missing, this might be the cause.

Install your new files by running <tt class="xref py py-obj docutils literal">python setup.py build</tt> and <tt class="xref py py-obj docutils literal">python setup.py

install</tt> followed by <tt class="xref py py-obj docutils literal">python boilerplate.py</tt>. The new pyplot.py file should now

have the latest changes.

</div>

</div>

Last updated on Sep 02, 2014.

Created using <a

href="http://sphinx-doc.org/">Sphinx</a> 1.3a0.

</div>

</body>

</html>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

FilesExpand file tree

coding_guide.html

Latest commit

History

coding_guide.html

File metadata and controls