better feedback
[samatjain:statusnet-backup.git] / README.md
1 StatusNet Timelines Backup
2 ==========================
3
4 Backs up StatusNet 1.0 streams in Activity Streams Atom format.
5
6 Installation
7 ------------
8
9 This tool isn't very robust yet; clone the repository, install the
10 dependencies, and backup into the folder you cloned it for best results.
11
12 Make sure you have Python 2.6 or 2.7 (it is 2to3 compatible but I've not
13 yet tested it), argparse (included with 2.7), dateutil, lxml, and requests.
14 On Ubuntu/Debian run:
15
16  $ sudo aptitude install python-dateutil python-requests python-lxml
17
18 Use
19 ---
20
21 If your username is billgates on Identi.ca, run:
22
23  $ StatusNet-Backup.py --username billgates
24
25 to backup your entire "user timeline" (your own notices) into a directory
26 called "user_timeline". If you want to backup your "friends timeline"
27 (the notices of those you subscribe to), run:
28
29  $ StatusNet-Backup.py --username billgates --timeline friends_timeline
30
31 This tool will start at page 1, and go as far back as possible until it
32 encounters an entry it's seen before (e.g. you can add the above to cron
33 to continually add new entries to your backup).
34
35 This tool can cause a lot of server load. Please use it during off-peak
36 times, and use it responsibly.
37
38 Known Issues
39 ------------
40
41 Also see the TODO file for those known issues/bugs that don't have a longer explanation.
42
43 ### Unicode problems
44
45 This tool works on Ubuntu 9.10. However, when I run it on identical (as far
46 as I can tell) Debian testing system, I get a Python Unicode error:
47
48  Traceback (most recent call last):
49    File "Identica-Backup.py", line 157, in <module>
50      main()
51    File "Identica-Backup.py", line 120, in main
52      document = etree.fromstring(raw_document)
53    File "lxml.etree.pyx", line 2743, in lxml.etree.fromstring (src/lxml/lxml.etree.c:52665)
54    File "parser.pxi", line 1564, in lxml.etree._parseMemoryDocument (src/lxml/lxml.etree.c:79843)
55  ValueError: Unicode strings with encoding declaration are not supported.
56
57 The error is from lxml: it is claiming that a document it attempts to parse
58 (from Identi.ca/your StatusNet installation) says it is not Unicode—when it
59 is! Again, the same thing works on Ubuntu, and I've no idea how to fix this.
60 If you've an idea how to FIX it (i.e. I don't want your it's-MY-fault-
61 Unicode-is-a-headache-in-Python lecture), please let me know.
62
63 ### Incomplete backups
64
65 The first time you run this tool, it'll attempt to backup your entire timeline.
66
67 But what if something happens before it finishes? At the moment, the tool
68 does not resume, and you have to handle the situation manually. When it
69 fails, take note of the last page number processed. Then, run with --page
70 and --force to start downloading from that page again. E.g.:
71
72  $ StatusNet-Backup.py --username billgates --page 43 --force
73
74 Details
75 -------
76
77 This tool saves timelines in [Activity Streams Atom format][as-atom] as is
78 made available from StatusNet 1.0 or later.
79
80   [as-atom]: http://activitystrea.ms/specs/atom/1.0/
81
82 Each entry (i.e. notice, poll, etc) is saved as an individual file.
83
84 There isn't a tool to import this back into a StatusNet installation.
85 I'm working on it. But, at least, you've a backup in a future-proof,
86 standardized format.
87
88 This tool is tailored for use w/ StatusNet, but could be modified easily
89 to backup anything that exports Activity Streams Atom—that includes
90 Flattr, Google Buzz, etc.
91
92 License
93 -------
94
95 Copyright © 2011 Samat K Jain.
96
97 This program is free software: you can redistribute it and/or modify
98 it under the terms of the GNU General Public License as published by
99 the Free Software Foundation, either version 3 of the License, or
100 (at your option) any later version.
101
102 This program is distributed in the hope that it will be useful,
103 but WITHOUT ANY WARRANTY; without even the implied warranty of
104 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
105 GNU General Public License for more details.
106
107 You should have received a copy of the GNU General Public License
108 along with this program.  If not, see <http://www.gnu.org/licenses/>.