Mercurial > louis > ofxstatement-us-hsbc

annotate README.rst @ 2:9e762b062264

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