Mercurial > louis > ofxstatement-us-hsbc

comparison README.rst @ 1:103ad506a83d

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
More detailed docs on creating ofxstatement plugins
author Andrey Lebedev <andrey@lebedev.lt>
date Sat, 02 Nov 2013 15:55:45 +0200
parents 1f85ed8ed469
children 9e762b062264
comparison
equal deleted inserted replaced
0:1f85ed8ed469 1:103ad506a83d
13 13
14 14
15 Users of ofxstatement have developed several plugins for their banks. They are 15 Users of ofxstatement have developed several plugins for their banks. They are
16 listed on main `ofxstatement`_ site. If your bank is missing, you can develop 16 listed on main `ofxstatement`_ site. If your bank is missing, you can develop
17 your own plugin. 17 your own plugin.
18
19 Setting up development environment
20 ==================================
21
22 It is recommended to use ``virtualenv`` make a clean development environment.
23 Setting up dev environment for writing a plugin is easy::
24
25 $ git clone https://github.com/kedder/ofxstatement-sample ofxstatement- yourbank
26 $ cd ofxstatement-yourbank
27 $ virtualenv -p python3 --no-site-packages .venv
28 $ . .venv/bin/activate
29 (.venv)$ python setup.py develop
30
31 This will download all the dependencies and install them into your virtual
32 environment. After this, you should be able to do::
33
34 (.venv)$ ofxstatement list-plugins
35 The following plugins are available:
36
37 sample Sample plugin (for developers only)
38
39
40
41 Your own plugin
42 ===============
43
44 To create your own plugin, follow these steps:
45
46 * Edit ``setup.py`` and provide relevant metadata for your plugin. Pay
47 close attention to ``entry_points`` parameter to ``setup`` function: it
48 lists plugins you are registering within ofxstatement. Give meaningful
49 name to the plugin and provide plugin class name
50 * Replace contents of ``README.rst`` with description of your plugin
51 * Rename ``ofxstatement/plugins/sample.py`` to match plugin package name
52 you have provided in ``entry_points`` parameter.
53 * Open renamed sample.py and rename ``SamplePlugin`` and ``SampleParser``
54 classes to match your plugin class name.
55 * Now, draw the rest of the owl (c).
56
57 .. _ofxstatement-sample: https://github.com/kedder/ofxstatement-sample
58
59 Your ``StatementParser`` is the main object that does all the hard work. It
60 has only one public method: ``parse()``, that should return
61 ``ofxstatement.statement.Statement`` object, filled with data from given input.
62 The default implementation, however, splits this work into two parts:
63 ``split_records()`` to split the whole file into logical parts, e.g.
64 transaction records, and ``parse_record()`` to extract information from
65 individual record. See ``src/ofxstatement/parser.py`` for details. If your
66 statement' format looks like CSV file, you might find ``CsvStatementParser``
67 class useful: it simplifies mapping bettween CSV columns and ``StatementLine``
68 attributes.
69
70 ``Plugin`` interface consists only of ``get_parser()`` method, that returns
71 configured StatementParser object for given input filename. Docstrings on
72 Plugin class is also useful for describing the purpose of your plugin. First
73 line of it is visible in ``ofxstatement list-plugins`` output.
74
75 Testing
76 =======
77
78 Test your code as you would do with any other project. To make sure
79 ofxstatement is still able to load your plugin, run::
80
81 (.venv)$ ofxstatement list-plugins
82
83 You should be able to see your plugin listed.
84
85 After you are done
86 ==================
87
88 After your plugin is ready, feel free to open an issue on `ofxstatement`_
89 project to include your plugin in "known plugin list". That would hopefully
90 make life of other clients of your bank easier.