Source code for pykern.pkexample
# -*- coding: utf-8 -*-
u"""Demonstrates a RadiaSoft style module.
This module demonstrates how we code at RadiaSoft. In general
we follow the `Google Python Style Guide
<http://google.github.io/styleguide/pyguide.html>`_ and the
`Sphinx Napoleon Google Docstrings Example <http://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html>`_.
Some Rules:
We adhere to PEP8 unless overruled by Google's Style Guide or
explicit rules such as:
1. Indent by four (4) spaces and no tabs.
#. Avoid lines over 80 characters. Not everybody's laptop
can show two 80+ char pages side by side.
#. All modules are Python 2 and 3 compatible.
#. Modules are divided into groups of declarations: public constants,
private constants, public global variables, private global
variables, public classes, private classes, public functions,
and private functions. Within each group, the declarations are
sorted alphabetically.
#. Logs, exceptions and assertions contain values, not
just messages. If a value is in error, include it in the
message along with the expected value, range, etc.
#. `:func:pykern.pkdebug.pkdp` to print logging messages,
and `:func:pykern.pkdebug.pkdc` to print trace messages.
#. Configuration is specified by `:mod:pykern.pkconfig`.
#. Use single quotes for strings. Use double quotes for docstrings.
#. TODO(robnagler) is how we represent things to do in a comment
Docstrings begin and end with three double quotes ("). On the line
with the beginning double quotes, you write a one line summary
of the function, class, or module.
:copyright: Copyright (c) 2016 RadiaSoft LLC. All Rights Reserved.
:license: http://www.apache.org/licenses/LICENSE-2.0.html
"""
from __future__ import absolute_import, division, print_function
# Imports are sorted alphabetically
# pykern imports are "from" since all modules begin with "pk" so they are unique
from pykern import pkconfig
# Import pkdc and pkdp functions directly. Mostly we import modules and
# qualify uses
from pykern.pkdebug import pkdc, pkdp
# We don't follow PEP8 here. Global variables/constants are separated by one blank
# line.
#: First constant is first alphabetically
ONE = 1
#: Another constant
ZIPPITY = 'doodah'
# Private constant is not documented with '#:'
_SSSHHH = 39
#: The module's config is a public variable. It is initialized at the end.
cfg = None
# Something private isn't publicly documented.
_priv_var = 123
# Two blank lines between functions and classes at the global level
[docs]class EMA(object):
"""Exponential moving average
Used as a demonstration of numerical computations. We document
the __init__ method at the class level, since it is an
implicit function call.
Args:
length (int): iterations
Attributes:
average (float): current value of the average
length (int): time period
"""
def __init__(self, length):
self.length = int(length)
assert length > 0, \
'{}: length must be greater than 0'.format(length)
self._alpha = 2.0 / (float(length) + 1.0)
self.average = None
[docs] def compute(self, value):
"""Compute the next value in the average
Args:
value (float): next number in the average
Returns:
float: current value of the average
"""
if self.average is None:
self.average = value
else:
self.average += self._alpha * (value - self.average)
return self.average
[docs] def value(self):
"""Get the average
Returns:
float: current value of the average
"""
assert self.average is not None, \
'self.average is None and has not been initialized'
return self.average
def _Privy(object):
"""This is a private class that does nothing"""
pass
def _cfg_length(anything):
"""Configuration parser for any_length
Args:
anything (object): configured value
Returns:
int: value between 1 and 999
"""
anything = int(anything)
assert 0 < anything <= 999, \
'{}: any_length must be from 1 to 999'
return anything
# Finally we assign any length. Note that we include a trailing , at the
# end of every line in a list so that you don't have to remember to
# add the comma when you add another line.
cfg = pkconfig.init(
any_length=(1, _cfg_length, 'A length used by this module'),
)