README

A Python 3.2+ package for various BlackBerry 10/BlackBerry Android-related functions and scripts.

Packaged Executables

As of version 2.3.0 (18 December 2015), most scripts are packaged as Windows executables on GitHub.

To use, just download the bbarchivist-<version>-<system bit> archive attached to the latest release, unpack somewhere and double click an executable.

As of version 4.0.0 (2 September 2019), 32-bit Windows executables have been discontinued.

Executables are prepared with PyInstaller. Distributing them as of Windows 10 and Python 3.5+ requires the Windows 10 SDK, thanks to Universal CRT.

Alternatively, if you require full functionality or Linux/Mac/BSD support, keep reading.

Installation

Requires Python >=3.2, with 3.7 or later preferred.

To get the latest stable version, install with pip:

$ pip install bbarchivist

If you want the latest development version, clone from Git and install with setuptools:

$ git clone https://github.com/thurask/bbarchivist.git
$ cd bbarchivist
$ python setup.py install

If you have Git LFS, the data files will download automatically. If you don't have Git LFS, then run the download_dats.py script in this folder. The data files will be considered different with regards to git, so be warned.

Python Libraries

This library requires the Requests, appdirs, user_agent, and Beautiful Soup 4 libraries. GPG support requires the python-gnupg library.

Python 3.2 further requires shutilwhich. Installation of shutilwhich on Python 3.3+ has no effect, so it's unnecessary.

The optional simplejson module is installed on Python 3.3+, for improved performance with dealing with JSON.

The optional defusedxml module is installed for safer XML handling. Use defusedxml 0.4.1 if you're using Python 3.2 or 3.3.

External Programs

Copies of cap.exe and cfp.exe are included. Windows can directly access both .exe files through the bb-cap and bb-cfp frontends.

7-Zip compression (default) uses p7zip (Linux/Mac/BSD) or 7-Zip (Windows). Zip and tar.xxx compression don't require external programs.

GPG support also requires some form of GPG client installed:

• Windows: Gpg4Win.
• Mac: GPGTools.
• Linux/BSD: GnuPG, if not already installed.

Testing

If you want to run the tests yourself, you'll also need pytest and httmock. Install from the requirements-devel.txt file with pip.

If you're testing on Python 3.2, install the mock backport as well.

Coverage requires installation of pytest-cov.

Testing of GnuPG/7-Zip functions requires setting up GnuPG/7-Zip in the first place.

Contributing

If you wish to contribute to this project, please do the following:

1. Fork and clone source from GitHub (requires Git LFS)
2. Make sure all tests run on your system (requires GPG, 7-Zip)
3. Make your changes on a new branch without breaking any tests, and add tests for your new code if applicable
4. Open a pull request on GitHub

Documentation

An overview of change history can be found in the CHANGES file.

Online documentation is hosted at ReadTheDocs.

Docs use Sphinx for automatic generation.

License

Copyright 2015-2019 Thurask <thuraski@hotmail.com> This work is free. You can redistribute it and/or modify it under the terms of the Do What The Fuck You Want To Public License, Version 2, as published by Sam Hocevar. See the LICENSE file for more details.