├── tests
├── __init__.py
└── unit
│ ├── __init__.py
│ └── technical_indicators.py
├── quantpy
├── gui
│ ├── __init__.py
│ ├── data
│ │ ├── app_menu.ui
│ │ └── quantpy.ui
│ ├── app.py
│ ├── settings.py
│ └── utils.py
├── fundamental_indicators.py
├── __init__.py
├── event_profiler.py
├── portfolio.py
└── technical_indicators.py
├── docs
├── requirements.txt
├── index.rst
├── _templates
│ └── layout.html
├── getting_started.rst
├── sphinxext
│ ├── numpydoc.py
│ ├── ipython_console_highlighting.py
│ ├── docscrape_sphinx.py
│ ├── inheritance_diagram.py
│ ├── docscrape.py
│ └── apigen.py
├── make.bat
├── Makefile
├── conf.py
└── _static
│ └── default.css
├── .gitignore
├── examples
├── efficient_frontier_plot_ex.py
├── nplot_ex.py
├── min_variance_returns_ex.py
└── event_ex.py
├── setup.py
├── CHANGES.txt
├── LICENSE
└── README.md
/tests/__init__.py:
--------------------------------------------------------------------------------
1 |
--------------------------------------------------------------------------------
/quantpy/gui/__init__.py:
--------------------------------------------------------------------------------
1 |
--------------------------------------------------------------------------------
/tests/unit/__init__.py:
--------------------------------------------------------------------------------
1 |
--------------------------------------------------------------------------------
/quantpy/fundamental_indicators.py:
--------------------------------------------------------------------------------
1 | def peg():
2 | pass
3 |
--------------------------------------------------------------------------------
/docs/requirements.txt:
--------------------------------------------------------------------------------
1 | f2py
2 | numpy
3 | matplotlib
4 | pandas
5 |
--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
1 | *pyc
2 | *swp
3 | docs/_build
4 | build
5 | .idea/
6 | .project
7 | .pydevproject
8 |
9 |
--------------------------------------------------------------------------------
/examples/efficient_frontier_plot_ex.py:
--------------------------------------------------------------------------------
1 | # Example plotting effienct frontier.
2 |
3 | import quantpy as qp
4 |
5 | # Grap portfolio
6 | P = qp.Portfolio(['GOOG','IBM','INTC','MSFT','AAPL'])
7 |
8 | # Plot effiecent frontier
9 | P.efficient_frontier_plot()
10 |
--------------------------------------------------------------------------------
/quantpy/__init__.py:
--------------------------------------------------------------------------------
1 | import sys
2 |
3 | from quantpy.portfolio import Portfolio
4 | from quantpy.event_profiler import *
5 | from quantpy.fundamental_indicators import *
6 | from quantpy.technical_indicators import *
7 |
8 |
9 | if sys.version > '3':
10 | long = int
11 |
--------------------------------------------------------------------------------
/examples/nplot_ex.py:
--------------------------------------------------------------------------------
1 | # Example plotting returns.
2 | from pylab import *
3 | import quantpy as qp
4 |
5 | # Get symbols.
6 | syms = ['IBM','GOOG','MSFT','AAPL','INTC']
7 | cols = ['b','r','g','k','m','y']
8 |
9 | # Get portfolio
10 | P = qp.Portfolio(syms)
11 |
12 | # Make plots of normalized returns.
13 | for sym,col in zip(syms,cols):
14 | P.nplot(sym,col)
15 | show()
16 |
--------------------------------------------------------------------------------
/setup.py:
--------------------------------------------------------------------------------
1 | from distutils.core import setup
2 |
3 | setup(
4 | name='QuantPy',
5 | version='0.1',
6 | author='Joseph Smidt',
7 | author_email='josephsmidt@gmail.com',
8 | packages=['quantpy'],
9 | url='https://github.com/jsmidt/QuantPy',
10 | license='LICENSE',
11 | description='A framework for quantitative finance In python',
12 | long_description=open('README.md').read(),
13 | install_requires=[
14 | "pandas >= 0.10.0",
15 | "matplotlib >= 1.1.0",
16 | ],
17 | )
18 |
--------------------------------------------------------------------------------
/docs/index.rst:
--------------------------------------------------------------------------------
1 | .. QuantPy documentation master file, created by
2 | sphinx-quickstart on Thu Mar 7 12:45:01 2013.
3 | You can adapt this file completely to your liking, but it should at least
4 | contain the root `toctree` directive.
5 |
6 | Welcome to QuantPy's documentation!
7 | ===================================
8 |
9 | Contents:
10 |
11 | .. toctree::
12 | :maxdepth: 2
13 |
14 | getting_started.rst
15 |
16 | Indices and tables
17 | ==================
18 |
19 | * :ref:`genindex`
20 | * :ref:`modindex`
21 | * :ref:`search`
22 |
23 |
--------------------------------------------------------------------------------
/examples/min_variance_returns_ex.py:
--------------------------------------------------------------------------------
1 | from pylab import *
2 | import quantpy as qp
3 |
4 | # Get portfolio.
5 | P = qp.Portfolio(['IBM','GOOG','MSFT','AAPL','INTC'])
6 |
7 | # Calculate the returns buying 1 share of everything.
8 | bb = P.ret_for_w(ones(5))
9 | cumsum(bb).plot(color='r',label='Buy and Hold Equally.')
10 | mm = cumsum(bb)[-1]
11 |
12 | # Find the optimal weighting that yields the same return with minimum variance.
13 | w = P.min_var_w_ret(mm)
14 | aa = P.ret_for_w(w)
15 | cumsum(aa).plot(label='Same return but min variance.')
16 | legend(loc='best',shadow=True, fancybox=True)
17 | show()
18 |
19 |
20 |
--------------------------------------------------------------------------------
/quantpy/gui/data/app_menu.ui:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
19 |
20 |
--------------------------------------------------------------------------------
/docs/_templates/layout.html:
--------------------------------------------------------------------------------
1 | {% extends "!layout.html" %}
2 |
3 |
4 | {% block rootrellink %}
5 | home|
6 | search|
7 | {% endblock %}
8 |
9 |
10 | {% block relbar1 %}
11 |
12 |
13 |
15 |
%s' %
355 | (path, name, name, image_map))
356 |
357 | def latex_output_graph(self, node):
358 | """
359 | Output the graph for LaTeX. This will insert a PDF.
360 | """
361 | graph = node['graph']
362 | parts = node['parts']
363 |
364 | graph_hash = get_graph_hash(node)
365 | name = "inheritance%s" % graph_hash
366 | dest_path = os.path.abspath(os.path.join(setup.app.builder.outdir, '_images'))
367 | if not os.path.exists(dest_path):
368 | os.makedirs(dest_path)
369 | pdf_path = os.path.abspath(os.path.join(dest_path, name + ".pdf"))
370 |
371 | graph.run_dot(['-Tpdf', '-o%s' % pdf_path],
372 | name, parts, graph_options={'size': '"6.0,6.0"'})
373 | return '\n\\includegraphics{%s}\n\n' % pdf_path
374 |
375 | def visit_inheritance_diagram(inner_func):
376 | """
377 | This is just a wrapper around html/latex_output_graph to make it
378 | easier to handle errors and insert warnings.
379 | """
380 | def visitor(self, node):
381 | try:
382 | content = inner_func(self, node)
383 | except DotException, e:
384 | # Insert the exception as a warning in the document
385 | warning = self.document.reporter.warning(str(e), line=node.line)
386 | warning.parent = node
387 | node.children = [warning]
388 | else:
389 | source = self.document.attributes['source']
390 | self.body.append(content)
391 | node.children = []
392 | return visitor
393 |
394 | def do_nothing(self, node):
395 | pass
396 |
397 | def setup(app):
398 | setup.app = app
399 | setup.confdir = app.confdir
400 |
401 | app.add_node(
402 | inheritance_diagram,
403 | latex=(visit_inheritance_diagram(latex_output_graph), do_nothing),
404 | html=(visit_inheritance_diagram(html_output_graph), do_nothing))
405 | app.add_directive(
406 | 'inheritance-diagram', inheritance_diagram_directive,
407 | False, (1, 100, 0), parts = directives.nonnegative_int)
408 |
--------------------------------------------------------------------------------
/docs/sphinxext/docscrape.py:
--------------------------------------------------------------------------------
1 | """Extract reference documentation from the NumPy source tree.
2 |
3 | """
4 |
5 | import inspect
6 | import textwrap
7 | import re
8 | import pydoc
9 | from StringIO import StringIO
10 | from warnings import warn
11 | 4
12 | class Reader(object):
13 | """A line-based string reader.
14 |
15 | """
16 | def __init__(self, data):
17 | """
18 | Parameters
19 | ----------
20 | data : str
21 | String with lines separated by '\n'.
22 |
23 | """
24 | if isinstance(data,list):
25 | self._str = data
26 | else:
27 | self._str = data.split('\n') # store string as list of lines
28 |
29 | self.reset()
30 |
31 | def __getitem__(self, n):
32 | return self._str[n]
33 |
34 | def reset(self):
35 | self._l = 0 # current line nr
36 |
37 | def read(self):
38 | if not self.eof():
39 | out = self[self._l]
40 | self._l += 1
41 | return out
42 | else:
43 | return ''
44 |
45 | def seek_next_non_empty_line(self):
46 | for l in self[self._l:]:
47 | if l.strip():
48 | break
49 | else:
50 | self._l += 1
51 |
52 | def eof(self):
53 | return self._l >= len(self._str)
54 |
55 | def read_to_condition(self, condition_func):
56 | start = self._l
57 | for line in self[start:]:
58 | if condition_func(line):
59 | return self[start:self._l]
60 | self._l += 1
61 | if self.eof():
62 | return self[start:self._l+1]
63 | return []
64 |
65 | def read_to_next_empty_line(self):
66 | self.seek_next_non_empty_line()
67 | def is_empty(line):
68 | return not line.strip()
69 | return self.read_to_condition(is_empty)
70 |
71 | def read_to_next_unindented_line(self):
72 | def is_unindented(line):
73 | return (line.strip() and (len(line.lstrip()) == len(line)))
74 | return self.read_to_condition(is_unindented)
75 |
76 | def peek(self,n=0):
77 | if self._l + n < len(self._str):
78 | return self[self._l + n]
79 | else:
80 | return ''
81 |
82 | def is_empty(self):
83 | return not ''.join(self._str).strip()
84 |
85 |
86 | class NumpyDocString(object):
87 | def __init__(self,docstring):
88 | docstring = textwrap.dedent(docstring).split('\n')
89 |
90 | self._doc = Reader(docstring)
91 | self._parsed_data = {
92 | 'Signature': '',
93 | 'Summary': [''],
94 | 'Extended Summary': [],
95 | 'Parameters': [],
96 | 'Returns': [],
97 | 'Raises': [],
98 | 'Warns': [],
99 | 'Other Parameters': [],
100 | 'Attributes': [],
101 | 'Methods': [],
102 | 'See Also': [],
103 | 'Notes': [],
104 | 'Warnings': [],
105 | 'References': '',
106 | 'Examples': '',
107 | 'index': {}
108 | }
109 |
110 | self._parse()
111 |
112 | def __getitem__(self,key):
113 | return self._parsed_data[key]
114 |
115 | def __setitem__(self,key,val):
116 | if not self._parsed_data.has_key(key):
117 | warn("Unknown section %s" % key)
118 | else:
119 | self._parsed_data[key] = val
120 |
121 | def _is_at_section(self):
122 | self._doc.seek_next_non_empty_line()
123 |
124 | if self._doc.eof():
125 | return False
126 |
127 | l1 = self._doc.peek().strip() # e.g. Parameters
128 |
129 | if l1.startswith('.. index::'):
130 | return True
131 |
132 | l2 = self._doc.peek(1).strip() # ---------- or ==========
133 | return l2.startswith('-'*len(l1)) or l2.startswith('='*len(l1))
134 |
135 | def _strip(self,doc):
136 | i = 0
137 | j = 0
138 | for i,line in enumerate(doc):
139 | if line.strip(): break
140 |
141 | for j,line in enumerate(doc[::-1]):
142 | if line.strip(): break
143 |
144 | return doc[i:len(doc)-j]
145 |
146 | def _read_to_next_section(self):
147 | section = self._doc.read_to_next_empty_line()
148 |
149 | while not self._is_at_section() and not self._doc.eof():
150 | if not self._doc.peek(-1).strip(): # previous line was empty
151 | section += ['']
152 |
153 | section += self._doc.read_to_next_empty_line()
154 |
155 | return section
156 |
157 | def _read_sections(self):
158 | while not self._doc.eof():
159 | data = self._read_to_next_section()
160 | name = data[0].strip()
161 |
162 | if name.startswith('..'): # index section
163 | yield name, data[1:]
164 | elif len(data) < 2:
165 | yield StopIteration
166 | else:
167 | yield name, self._strip(data[2:])
168 |
169 | def _parse_param_list(self,content):
170 | r = Reader(content)
171 | params = []
172 | while not r.eof():
173 | header = r.read().strip()
174 | if ' : ' in header:
175 | arg_name, arg_type = header.split(' : ')[:2]
176 | else:
177 | arg_name, arg_type = header, ''
178 |
179 | desc = r.read_to_next_unindented_line()
180 | desc = dedent_lines(desc)
181 |
182 | params.append((arg_name,arg_type,desc))
183 |
184 | return params
185 |
186 |
187 | _name_rgx = re.compile(r"^\s*(:(?P\w+):`(?P[a-zA-Z0-9_.-]+)`|"
188 | r" (?P[a-zA-Z0-9_.-]+))\s*", re.X)
189 | def _parse_see_also(self, content):
190 | """
191 | func_name : Descriptive text
192 | continued text
193 | another_func_name : Descriptive text
194 | func_name1, func_name2, :meth:`func_name`, func_name3
195 |
196 | """
197 | items = []
198 |
199 | def parse_item_name(text):
200 | """Match ':role:`name`' or 'name'"""
201 | m = self._name_rgx.match(text)
202 | if m:
203 | g = m.groups()
204 | if g[1] is None:
205 | return g[3], None
206 | else:
207 | return g[2], g[1]
208 | raise ValueError("%s is not a item name" % text)
209 |
210 | def push_item(name, rest):
211 | if not name:
212 | return
213 | name, role = parse_item_name(name)
214 | items.append((name, list(rest), role))
215 | del rest[:]
216 |
217 | current_func = None
218 | rest = []
219 |
220 | for line in content:
221 | if not line.strip(): continue
222 |
223 | m = self._name_rgx.match(line)
224 | if m and line[m.end():].strip().startswith(':'):
225 | push_item(current_func, rest)
226 | current_func, line = line[:m.end()], line[m.end():]
227 | rest = [line.split(':', 1)[1].strip()]
228 | if not rest[0]:
229 | rest = []
230 | elif not line.startswith(' '):
231 | push_item(current_func, rest)
232 | current_func = None
233 | if ',' in line:
234 | for func in line.split(','):
235 | push_item(func, [])
236 | elif line.strip():
237 | current_func = line
238 | elif current_func is not None:
239 | rest.append(line.strip())
240 | push_item(current_func, rest)
241 | return items
242 |
243 | def _parse_index(self, section, content):
244 | """
245 | .. index: default
246 | :refguide: something, else, and more
247 |
248 | """
249 | def strip_each_in(lst):
250 | return [s.strip() for s in lst]
251 |
252 | out = {}
253 | section = section.split('::')
254 | if len(section) > 1:
255 | out['default'] = strip_each_in(section[1].split(','))[0]
256 | for line in content:
257 | line = line.split(':')
258 | if len(line) > 2:
259 | out[line[1]] = strip_each_in(line[2].split(','))
260 | return out
261 |
262 | def _parse_summary(self):
263 | """Grab signature (if given) and summary"""
264 | if self._is_at_section():
265 | return
266 |
267 | summary = self._doc.read_to_next_empty_line()
268 | summary_str = " ".join([s.strip() for s in summary]).strip()
269 | if re.compile('^([\w., ]+=)?\s*[\w\.]+\(.*\)$').match(summary_str):
270 | self['Signature'] = summary_str
271 | if not self._is_at_section():
272 | self['Summary'] = self._doc.read_to_next_empty_line()
273 | else:
274 | self['Summary'] = summary
275 |
276 | if not self._is_at_section():
277 | self['Extended Summary'] = self._read_to_next_section()
278 |
279 | def _parse(self):
280 | self._doc.reset()
281 | self._parse_summary()
282 |
283 | for (section,content) in self._read_sections():
284 | if not section.startswith('..'):
285 | section = ' '.join([s.capitalize() for s in section.split(' ')])
286 | if section in ('Parameters', 'Attributes', 'Methods',
287 | 'Returns', 'Raises', 'Warns'):
288 | self[section] = self._parse_param_list(content)
289 | elif section.startswith('.. index::'):
290 | self['index'] = self._parse_index(section, content)
291 | elif section == 'See Also':
292 | self['See Also'] = self._parse_see_also(content)
293 | else:
294 | self[section] = content
295 |
296 | # string conversion routines
297 |
298 | def _str_header(self, name, symbol='-'):
299 | return [name, len(name)*symbol]
300 |
301 | def _str_indent(self, doc, indent=4):
302 | out = []
303 | for line in doc:
304 | out += [' '*indent + line]
305 | return out
306 |
307 | def _str_signature(self):
308 | if self['Signature']:
309 | return [self['Signature'].replace('*','\*')] + ['']
310 | else:
311 | return ['']
312 |
313 | def _str_summary(self):
314 | if self['Summary']:
315 | return self['Summary'] + ['']
316 | else:
317 | return []
318 |
319 | def _str_extended_summary(self):
320 | if self['Extended Summary']:
321 | return self['Extended Summary'] + ['']
322 | else:
323 | return []
324 |
325 | def _str_param_list(self, name):
326 | out = []
327 | if self[name]:
328 | out += self._str_header(name)
329 | for param,param_type,desc in self[name]:
330 | out += ['%s : %s' % (param, param_type)]
331 | out += self._str_indent(desc)
332 | out += ['']
333 | return out
334 |
335 | def _str_section(self, name):
336 | out = []
337 | if self[name]:
338 | out += self._str_header(name)
339 | out += self[name]
340 | out += ['']
341 | return out
342 |
343 | def _str_see_also(self, func_role):
344 | if not self['See Also']: return []
345 | out = []
346 | out += self._str_header("See Also")
347 | last_had_desc = True
348 | for func, desc, role in self['See Also']:
349 | if role:
350 | link = ':%s:`%s`' % (role, func)
351 | elif func_role:
352 | link = ':%s:`%s`' % (func_role, func)
353 | else:
354 | link = "`%s`_" % func
355 | if desc or last_had_desc:
356 | out += ['']
357 | out += [link]
358 | else:
359 | out[-1] += ", %s" % link
360 | if desc:
361 | out += self._str_indent([' '.join(desc)])
362 | last_had_desc = True
363 | else:
364 | last_had_desc = False
365 | out += ['']
366 | return out
367 |
368 | def _str_index(self):
369 | idx = self['index']
370 | out = []
371 | out += ['.. index:: %s' % idx.get('default','')]
372 | for section, references in idx.iteritems():
373 | if section == 'default':
374 | continue
375 | out += [' :%s: %s' % (section, ', '.join(references))]
376 | return out
377 |
378 | def __str__(self, func_role=''):
379 | out = []
380 | out += self._str_signature()
381 | out += self._str_summary()
382 | out += self._str_extended_summary()
383 | for param_list in ('Parameters','Returns','Raises'):
384 | out += self._str_param_list(param_list)
385 | out += self._str_section('Warnings')
386 | out += self._str_see_also(func_role)
387 | for s in ('Notes','References','Examples'):
388 | out += self._str_section(s)
389 | out += self._str_index()
390 | return '\n'.join(out)
391 |
392 |
393 | def indent(str,indent=4):
394 | indent_str = ' '*indent
395 | if str is None:
396 | return indent_str
397 | lines = str.split('\n')
398 | return '\n'.join(indent_str + l for l in lines)
399 |
400 | def dedent_lines(lines):
401 | """Deindent a list of lines maximally"""
402 | return textwrap.dedent("\n".join(lines)).split("\n")
403 |
404 | def header(text, style='-'):
405 | return text + '\n' + style*len(text) + '\n'
406 |
407 |
408 | class FunctionDoc(NumpyDocString):
409 | def __init__(self, func, role='func', doc=None):
410 | self._f = func
411 | self._role = role # e.g. "func" or "meth"
412 | if doc is None:
413 | doc = inspect.getdoc(func) or ''
414 | try:
415 | NumpyDocString.__init__(self, doc)
416 | except ValueError, e:
417 | print '*'*78
418 | print "ERROR: '%s' while parsing `%s`" % (e, self._f)
419 | print '*'*78
420 | #print "Docstring follows:"
421 | #print doclines
422 | #print '='*78
423 |
424 | if not self['Signature']:
425 | func, func_name = self.get_func()
426 | try:
427 | # try to read signature
428 | argspec = inspect.getargspec(func)
429 | argspec = inspect.formatargspec(*argspec)
430 | argspec = argspec.replace('*','\*')
431 | signature = '%s%s' % (func_name, argspec)
432 | except TypeError, e:
433 | signature = '%s()' % func_name
434 | self['Signature'] = signature
435 |
436 | def get_func(self):
437 | func_name = getattr(self._f, '__name__', self.__class__.__name__)
438 | if inspect.isclass(self._f):
439 | func = getattr(self._f, '__call__', self._f.__init__)
440 | else:
441 | func = self._f
442 | return func, func_name
443 |
444 | def __str__(self):
445 | out = ''
446 |
447 | func, func_name = self.get_func()
448 | signature = self['Signature'].replace('*', '\*')
449 |
450 | roles = {'func': 'function',
451 | 'meth': 'method'}
452 |
453 | if self._role:
454 | if not roles.has_key(self._role):
455 | print "Warning: invalid role %s" % self._role
456 | out += '.. %s:: %s\n \n\n' % (roles.get(self._role,''),
457 | func_name)
458 |
459 | out += super(FunctionDoc, self).__str__(func_role=self._role)
460 | return out
461 |
462 |
463 | class ClassDoc(NumpyDocString):
464 | def __init__(self,cls,modulename='',func_doc=FunctionDoc,doc=None):
465 | if not inspect.isclass(cls):
466 | raise ValueError("Initialise using a class. Got %r" % cls)
467 | self._cls = cls
468 |
469 | if modulename and not modulename.endswith('.'):
470 | modulename += '.'
471 | self._mod = modulename
472 | self._name = cls.__name__
473 | self._func_doc = func_doc
474 |
475 | if doc is None:
476 | doc = pydoc.getdoc(cls)
477 |
478 | NumpyDocString.__init__(self, doc)
479 |
480 | @property
481 | def methods(self):
482 | return [name for name,func in inspect.getmembers(self._cls)
483 | if not name.startswith('_') and callable(func)]
484 |
485 | def __str__(self):
486 | out = ''
487 | out += super(ClassDoc, self).__str__()
488 | out += "\n\n"
489 |
490 | #for m in self.methods:
491 | # print "Parsing `%s`" % m
492 | # out += str(self._func_doc(getattr(self._cls,m), 'meth')) + '\n\n'
493 | # out += '.. index::\n single: %s; %s\n\n' % (self._name, m)
494 |
495 | return out
496 |
497 |
498 |
--------------------------------------------------------------------------------
/docs/sphinxext/apigen.py:
--------------------------------------------------------------------------------
1 | """Attempt to generate templates for module reference with Sphinx
2 |
3 | XXX - we exclude extension modules
4 |
5 | To include extension modules, first identify them as valid in the
6 | ``_uri2path`` method, then handle them in the ``_parse_module`` script.
7 |
8 | We get functions and classes by parsing the text of .py files.
9 | Alternatively we could import the modules for discovery, and we'd have
10 | to do that for extension modules. This would involve changing the
11 | ``_parse_module`` method to work via import and introspection, and
12 | might involve changing ``discover_modules`` (which determines which
13 | files are modules, and therefore which module URIs will be passed to
14 | ``_parse_module``).
15 |
16 | NOTE: this is a modified version of a script originally shipped with the
17 | PyMVPA project, which we've adapted for NIPY use. PyMVPA is an MIT-licensed
18 | project."""
19 |
20 | # Stdlib imports
21 | import os
22 | import re
23 |
24 | # Functions and classes
25 | class ApiDocWriter(object):
26 | ''' Class for automatic detection and parsing of API docs
27 | to Sphinx-parsable reST format'''
28 |
29 | # only separating first two levels
30 | rst_section_levels = ['*', '=', '-', '~', '^']
31 |
32 | def __init__(self,
33 | package_name,
34 | rst_extension='.rst',
35 | package_skip_patterns=None,
36 | module_skip_patterns=None,
37 | ):
38 | ''' Initialize package for parsing
39 |
40 | Parameters
41 | ----------
42 | package_name : string
43 | Name of the top-level package. *package_name* must be the
44 | name of an importable package
45 | rst_extension : string, optional
46 | Extension for reST files, default '.rst'
47 | package_skip_patterns : None or sequence of {strings, regexps}
48 | Sequence of strings giving URIs of packages to be excluded
49 | Operates on the package path, starting at (including) the
50 | first dot in the package path, after *package_name* - so,
51 | if *package_name* is ``sphinx``, then ``sphinx.util`` will
52 | result in ``.util`` being passed for earching by these
53 | regexps. If is None, gives default. Default is:
54 | ['\.tests$']
55 | module_skip_patterns : None or sequence
56 | Sequence of strings giving URIs of modules to be excluded
57 | Operates on the module name including preceding URI path,
58 | back to the first dot after *package_name*. For example
59 | ``sphinx.util.console`` results in the string to search of
60 | ``.util.console``
61 | If is None, gives default. Default is:
62 | ['\.setup$', '\._']
63 | '''
64 | if package_skip_patterns is None:
65 | package_skip_patterns = ['\\.tests$']
66 | if module_skip_patterns is None:
67 | module_skip_patterns = ['\\.setup$', '\\._']
68 | self.package_name = package_name
69 | self.rst_extension = rst_extension
70 | self.package_skip_patterns = package_skip_patterns
71 | self.module_skip_patterns = module_skip_patterns
72 |
73 | def get_package_name(self):
74 | return self._package_name
75 |
76 | def set_package_name(self, package_name):
77 | ''' Set package_name
78 |
79 | >>> docwriter = ApiDocWriter('sphinx')
80 | >>> import sphinx
81 | >>> docwriter.root_path == sphinx.__path__[0]
82 | True
83 | >>> docwriter.package_name = 'docutils'
84 | >>> import docutils
85 | >>> docwriter.root_path == docutils.__path__[0]
86 | True
87 | '''
88 | # It's also possible to imagine caching the module parsing here
89 | self._package_name = package_name
90 | self.root_module = __import__(package_name)
91 | self.root_path = self.root_module.__path__[0]
92 | self.written_modules = None
93 |
94 | package_name = property(get_package_name, set_package_name, None,
95 | 'get/set package_name')
96 |
97 | def _get_object_name(self, line):
98 | ''' Get second token in line
99 | >>> docwriter = ApiDocWriter('sphinx')
100 | >>> docwriter._get_object_name(" def func(): ")
101 | 'func'
102 | >>> docwriter._get_object_name(" class Klass(object): ")
103 | 'Klass'
104 | >>> docwriter._get_object_name(" class Klass: ")
105 | 'Klass'
106 | '''
107 | name = line.split()[1].split('(')[0].strip()
108 | # in case we have classes which are not derived from object
109 | # ie. old style classes
110 | return name.rstrip(':')
111 |
112 | def _uri2path(self, uri):
113 | ''' Convert uri to absolute filepath
114 |
115 | Parameters
116 | ----------
117 | uri : string
118 | URI of python module to return path for
119 |
120 | Returns
121 | -------
122 | path : None or string
123 | Returns None if there is no valid path for this URI
124 | Otherwise returns absolute file system path for URI
125 |
126 | Examples
127 | --------
128 | >>> docwriter = ApiDocWriter('sphinx')
129 | >>> import sphinx
130 | >>> modpath = sphinx.__path__[0]
131 | >>> res = docwriter._uri2path('sphinx.builder')
132 | >>> res == os.path.join(modpath, 'builder.py')
133 | True
134 | >>> res = docwriter._uri2path('sphinx')
135 | >>> res == os.path.join(modpath, '__init__.py')
136 | True
137 | >>> docwriter._uri2path('sphinx.does_not_exist')
138 |
139 | '''
140 | if uri == self.package_name:
141 | return os.path.join(self.root_path, '__init__.py')
142 | path = uri.replace('.', os.path.sep)
143 | path = path.replace(self.package_name + os.path.sep, '')
144 | path = os.path.join(self.root_path, path)
145 | # XXX maybe check for extensions as well?
146 | if os.path.exists(path + '.py'): # file
147 | path += '.py'
148 | elif os.path.exists(os.path.join(path, '__init__.py')):
149 | path = os.path.join(path, '__init__.py')
150 | else:
151 | return None
152 | return path
153 |
154 | def _path2uri(self, dirpath):
155 | ''' Convert directory path to uri '''
156 | relpath = dirpath.replace(self.root_path, self.package_name)
157 | if relpath.startswith(os.path.sep):
158 | relpath = relpath[1:]
159 | return relpath.replace(os.path.sep, '.')
160 |
161 | def _parse_module(self, uri):
162 | ''' Parse module defined in *uri* '''
163 | filename = self._uri2path(uri)
164 | if filename is None:
165 | # nothing that we could handle here.
166 | return ([],[])
167 | f = open(filename, 'rt')
168 | functions, classes = self._parse_lines(f)
169 | f.close()
170 | return functions, classes
171 |
172 | def _parse_lines(self, linesource):
173 | ''' Parse lines of text for functions and classes '''
174 | functions = []
175 | classes = []
176 | for line in linesource:
177 | if line.startswith('def ') and line.count('('):
178 | # exclude private stuff
179 | name = self._get_object_name(line)
180 | if not name.startswith('_'):
181 | functions.append(name)
182 | elif line.startswith('class '):
183 | # exclude private stuff
184 | name = self._get_object_name(line)
185 | if not name.startswith('_'):
186 | classes.append(name)
187 | else:
188 | pass
189 | functions.sort()
190 | classes.sort()
191 | return functions, classes
192 |
193 | def generate_api_doc(self, uri):
194 | '''Make autodoc documentation template string for a module
195 |
196 | Parameters
197 | ----------
198 | uri : string
199 | python location of module - e.g 'sphinx.builder'
200 |
201 | Returns
202 | -------
203 | S : string
204 | Contents of API doc
205 | '''
206 | # get the names of all classes and functions
207 | functions, classes = self._parse_module(uri)
208 | if not len(functions) and not len(classes):
209 | print 'WARNING: Empty -',uri # dbg
210 | return ''
211 |
212 | # Make a shorter version of the uri that omits the package name for
213 | # titles
214 | uri_short = re.sub(r'^%s\.' % self.package_name,'',uri)
215 |
216 | ad = '.. AUTO-GENERATED FILE -- DO NOT EDIT!\n\n'
217 |
218 | chap_title = uri_short
219 | ad += (chap_title+'\n'+ self.rst_section_levels[1] * len(chap_title)
220 | + '\n\n')
221 |
222 | # Set the chapter title to read 'module' for all modules except for the
223 | # main packages
224 | if '.' in uri:
225 | title = 'Module: :mod:`' + uri_short + '`'
226 | else:
227 | title = ':mod:`' + uri_short + '`'
228 | ad += title + '\n' + self.rst_section_levels[2] * len(title)
229 |
230 | if len(classes):
231 | ad += '\nInheritance diagram for ``%s``:\n\n' % uri
232 | ad += '.. inheritance-diagram:: %s \n' % uri
233 | ad += ' :parts: 3\n'
234 |
235 | ad += '\n.. automodule:: ' + uri + '\n'
236 | ad += '\n.. currentmodule:: ' + uri + '\n'
237 | multi_class = len(classes) > 1
238 | multi_fx = len(functions) > 1
239 | if multi_class:
240 | ad += '\n' + 'Classes' + '\n' + \
241 | self.rst_section_levels[2] * 7 + '\n'
242 | elif len(classes) and multi_fx:
243 | ad += '\n' + 'Class' + '\n' + \
244 | self.rst_section_levels[2] * 5 + '\n'
245 | for c in classes:
246 | ad += '\n:class:`' + c + '`\n' \
247 | + self.rst_section_levels[multi_class + 2 ] * \
248 | (len(c)+9) + '\n\n'
249 | ad += '\n.. autoclass:: ' + c + '\n'
250 | # must NOT exclude from index to keep cross-refs working
251 | ad += ' :members:\n' \
252 | ' :undoc-members:\n' \
253 | ' :show-inheritance:\n' \
254 | ' :inherited-members:\n' \
255 | '\n' \
256 | ' .. automethod:: __init__\n'
257 | if multi_fx:
258 | ad += '\n' + 'Functions' + '\n' + \
259 | self.rst_section_levels[2] * 9 + '\n\n'
260 | elif len(functions) and multi_class:
261 | ad += '\n' + 'Function' + '\n' + \
262 | self.rst_section_levels[2] * 8 + '\n\n'
263 | for f in functions:
264 | # must NOT exclude from index to keep cross-refs working
265 | ad += '\n.. autofunction:: ' + uri + '.' + f + '\n\n'
266 | return ad
267 |
268 | def _survives_exclude(self, matchstr, match_type):
269 | ''' Returns True if *matchstr* does not match patterns
270 |
271 | ``self.package_name`` removed from front of string if present
272 |
273 | Examples
274 | --------
275 | >>> dw = ApiDocWriter('sphinx')
276 | >>> dw._survives_exclude('sphinx.okpkg', 'package')
277 | True
278 | >>> dw.package_skip_patterns.append('^\\.badpkg$')
279 | >>> dw._survives_exclude('sphinx.badpkg', 'package')
280 | False
281 | >>> dw._survives_exclude('sphinx.badpkg', 'module')
282 | True
283 | >>> dw._survives_exclude('sphinx.badmod', 'module')
284 | True
285 | >>> dw.module_skip_patterns.append('^\\.badmod$')
286 | >>> dw._survives_exclude('sphinx.badmod', 'module')
287 | False
288 | '''
289 | if match_type == 'module':
290 | patterns = self.module_skip_patterns
291 | elif match_type == 'package':
292 | patterns = self.package_skip_patterns
293 | else:
294 | raise ValueError('Cannot interpret match type "%s"'
295 | % match_type)
296 | # Match to URI without package name
297 | L = len(self.package_name)
298 | if matchstr[:L] == self.package_name:
299 | matchstr = matchstr[L:]
300 | for pat in patterns:
301 | try:
302 | pat.search
303 | except AttributeError:
304 | pat = re.compile(pat)
305 | if pat.search(matchstr):
306 | return False
307 | return True
308 |
309 | def discover_modules(self):
310 | ''' Return module sequence discovered from ``self.package_name``
311 |
312 |
313 | Parameters
314 | ----------
315 | None
316 |
317 | Returns
318 | -------
319 | mods : sequence
320 | Sequence of module names within ``self.package_name``
321 |
322 | Examples
323 | --------
324 | >>> dw = ApiDocWriter('sphinx')
325 | >>> mods = dw.discover_modules()
326 | >>> 'sphinx.util' in mods
327 | True
328 | >>> dw.package_skip_patterns.append('\.util$')
329 | >>> 'sphinx.util' in dw.discover_modules()
330 | False
331 | >>>
332 | '''
333 | modules = [self.package_name]
334 | # raw directory parsing
335 | for dirpath, dirnames, filenames in os.walk(self.root_path):
336 | # Check directory names for packages
337 | root_uri = self._path2uri(os.path.join(self.root_path,
338 | dirpath))
339 | for dirname in dirnames[:]: # copy list - we modify inplace
340 | package_uri = '.'.join((root_uri, dirname))
341 | if (self._uri2path(package_uri) and
342 | self._survives_exclude(package_uri, 'package')):
343 | modules.append(package_uri)
344 | else:
345 | dirnames.remove(dirname)
346 | # Check filenames for modules
347 | for filename in filenames:
348 | module_name = filename[:-3]
349 | module_uri = '.'.join((root_uri, module_name))
350 | if (self._uri2path(module_uri) and
351 | self._survives_exclude(module_uri, 'module')):
352 | modules.append(module_uri)
353 | return sorted(modules)
354 |
355 | def write_modules_api(self, modules,outdir):
356 | # write the list
357 | written_modules = []
358 | for m in modules:
359 | api_str = self.generate_api_doc(m)
360 | if not api_str:
361 | continue
362 | # write out to file
363 | outfile = os.path.join(outdir,
364 | m + self.rst_extension)
365 | fileobj = open(outfile, 'wt')
366 | fileobj.write(api_str)
367 | fileobj.close()
368 | written_modules.append(m)
369 | self.written_modules = written_modules
370 |
371 | def write_api_docs(self, outdir):
372 | """Generate API reST files.
373 |
374 | Parameters
375 | ----------
376 | outdir : string
377 | Directory name in which to store files
378 | We create automatic filenames for each module
379 |
380 | Returns
381 | -------
382 | None
383 |
384 | Notes
385 | -----
386 | Sets self.written_modules to list of written modules
387 | """
388 | if not os.path.exists(outdir):
389 | os.mkdir(outdir)
390 | # compose list of modules
391 | modules = self.discover_modules()
392 | self.write_modules_api(modules,outdir)
393 |
394 | def write_index(self, outdir, froot='gen', relative_to=None):
395 | """Make a reST API index file from written files
396 |
397 | Parameters
398 | ----------
399 | path : string
400 | Filename to write index to
401 | outdir : string
402 | Directory to which to write generated index file
403 | froot : string, optional
404 | root (filename without extension) of filename to write to
405 | Defaults to 'gen'. We add ``self.rst_extension``.
406 | relative_to : string
407 | path to which written filenames are relative. This
408 | component of the written file path will be removed from
409 | outdir, in the generated index. Default is None, meaning,
410 | leave path as it is.
411 | """
412 | if self.written_modules is None:
413 | raise ValueError('No modules written')
414 | # Get full filename path
415 | path = os.path.join(outdir, froot+self.rst_extension)
416 | # Path written into index is relative to rootpath
417 | if relative_to is not None:
418 | relpath = outdir.replace(relative_to + os.path.sep, '')
419 | else:
420 | relpath = outdir
421 | idx = open(path,'wt')
422 | w = idx.write
423 | w('.. AUTO-GENERATED FILE -- DO NOT EDIT!\n\n')
424 | w('.. toctree::\n\n')
425 | for f in self.written_modules:
426 | w(' %s\n' % os.path.join(relpath,f))
427 | idx.close()
428 |
--------------------------------------------------------------------------------