Mercurial > louis > ofxstatement-us-hsbc

comparison README.rst @ 7:829eb62755b0

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
First cut at an HSBC (USA) plugin
author Louis Opter <kalessin@kalessin.fr>
date Thu, 17 Nov 2016 16:25:12 -0800
parents 9e762b062264
children 28548158a325
comparison
equal deleted inserted replaced
6:5692e2a61764 7:829eb62755b0
1 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1 ofxstatement plugin for HSBC (USA)
2 Sample plugin for ofxstatement
3 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4
5 This project provides a boilerplate for custom plugins for ofxstatement.
6
7 `ofxstatement`_ is a tool to convert proprietary bank statement to OFX format,
8 suitable for importing to GnuCash. Plugin for ofxstatement parses a
9 particular proprietary bank statement format and produces common data
10 structure, that is then formatted into an OFX file.
11
12 .. _ofxstatement: https://github.com/kedder/ofxstatement
13
14
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
17 your own plugin.
18
19 Setting up development environment
20 ================================== 2 ==================================
21 3
22 It is recommended to use ``virtualenv`` make a clean development environment. 4 This only supports the ``ExportData.csv`` file you can download from the "money
23 Setting up dev environment for writing a plugin is easy:: 5 management" tool found within their online banking interface (`accessible
6 here`_).
24 7
25 $ git clone https://github.com/kedder/ofxstatement-sample ofxstatement-yourbank 8 ofxstatement can only process one account at a time, so make sure you export
26 $ cd ofxstatement-yourbank 9 each account separately into different files.
27 $ virtualenv -p python3 --no-site-packages .venv
28 $ . .venv/bin/activate
29 (.venv)$ python setup.py develop
30 10
31 This will download all the dependencies and install them into your virtual 11 I pretty much used this only once in November 2016 to import about around 2000
32 environment. After this, you should be able to do:: 12 transactions into GnuCash_. Your mileage may vary.
33 13
34 (.venv)$ ofxstatement list-plugins 14 .. _accessible here: http://www.us.hsbc.com/1/2/home/personal-banking/customers
35 The following plugins are available: 15 .. _GnuCash: http://www.gnucash.org/
36 16
37 sample Sample plugin (for developers only) 17 .. vim: set tw=80 spelllang=en spell:
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.