You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
This repo is archived. You can view files and clone it, but cannot push or open issues/pull-requests.

example.py 2.4 KiB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788
  1. """An example module to show autodoc style.
  2. Contains an example constant, :class:`Storage` class for storing objects and
  3. helper function :func:`store_integers` for storing only integers.
  4. """
  5. import datetime
  6. #: Example integer constant.
  7. INT_CONSTANT = 1
  8. #: Example integer constant.
  9. STR_CONSTANT = 'string'
  10. class Storage(object):
  11. """A class for storing objects.
  12. This is an example class to show autodoc style.
  13. It stores a list of objects and saves date of last appended item.
  14. Example usage::
  15. >>> storage = Storage(['foo', 'bar'])
  16. >>> storage.items
  17. ['foo', 'bar']
  18. >>> storage.last_updated
  19. datetime.datetime(2013, 8, 15, 13, 41, 38, 515797)
  20. >>> storage.add_item('baz')
  21. >>> storage.items
  22. ['foo', 'bar', 'baz']
  23. >>> storage.last_updated
  24. datetime.datetime(2013, 8, 15, 13, 41, 40, 595544)
  25. :param items:
  26. Optional list of items to start with.
  27. """
  28. def __init__(self, items=None):
  29. #: List of items, add new item using :meth:`add_item`.
  30. self.items = items or []
  31. #: :py:class:`datetime.datetime` of last item update, will be set
  32. #: to :py:meth:`datetime.datetime.now` on object instantiation.
  33. self.last_updated = datetime.datetime.now()
  34. def add_item(self, item):
  35. """Append item to the list.
  36. :attr:`last_updated` will be set to :py:meth:`datetime.datetime.now`.
  37. :param item:
  38. Something to append to :attr:`items`.
  39. """
  40. self.items.append(item)
  41. self.last_updated = datetime.datetime.now()
  42. def store_integers(items, allow_zero=True):
  43. """Store integers from the given list in a storage.
  44. This is an example function to show autodoc style.
  45. Return :class:`Storage` instance with integers from the given list.
  46. Examples::
  47. >>> storage = store_integers([1, 'foo', 2, 'bar', 0])
  48. >>> storage.items
  49. [1, 2, 0]
  50. >>> storage = store_integers([1, 'foo', 2, 'bar', 0], allow_zero=False)
  51. >>> storage.items
  52. [1, 2]
  53. :param items:
  54. List of objects of any type, only :class:`int` instances will be
  55. stored.
  56. :param allow_zero:
  57. Boolean -- if ``False``, ``0`` integers will be skipped.
  58. Defaults to ``True``.
  59. """
  60. ints = [x for x in items if isinstance(x, int) and (allow_zero or x != 0)]
  61. storage = Storage(ints)
  62. return storage