GitLocker: The Coding Marketplace

Description:

icemac.songbeamer 1.0

icemac.songbeamer

Library to read and write SongBeamer files.
This package is licensed under the MIT License, see LICENSE.TXT inside the
package.

Contents

icemac.songbeamer

Supported SongBeamer versions
Supported Python version
Running Tests
Hacking

Changes

1.0 (2018-11-02)

Backwards incompatible changes
Features

0.3 (2018-10-07)
0.2.0 (2012-10-31)
0.1.0 (2012-05-05)

To do

Implementations
Open Questions

Usage

Importing a .sng file
Accessing a file’s data
Exporting a .sng file

Supported SongBeamer versions
Currently Songbeamer versions 2 to 4 are supported. (Internal version
number in .sng files: #Version=3.)

Supported Python version
Runs only on Python 3.7. Older Python versions are not supported.

Running Tests
To run the tests call:
$ tox
(You maybe have to install tox beforehand using: pip install tox.)

Hacking
Fork me on: https://github.com:/icemac/icemac.songbeamer

Changes

1.0 (2018-11-02)

Backwards incompatible changes

The icemac.songbeamer.SNG instances no longer store the data on the
data attribute but it now behaves like a dict thus allowing direct dict
access to the data.
It is no longer possible to use attributes on icemac.songbeamer.SNG
instances to read and store encoded bytes data. Either read/write text data
from/to the icemac.songbeamer.SNG instance using the dict API or use
the parse function (see next item) to import resp. use .SNG.export()
to export the data encoded.
Add a function icemac.songbeamer.parse() converting a byte stream
into a icemac.songbeamer.SNG instance. It replaces the class method on
the SNG instance. It returns None if the data cannot be
parsed and it logs an error message.
Drop support for Python 3.5, 3.6 and PyPy3, thus only supporting Python 3.7
now.

Features

Add a function icemac.songbeamer.open() to open a file given by a path
and get a icemac.songbeamer.SNG instance.
Make .SNG.export() robust against missing text in songs.
Add a command line script songbeamer-xls-export exporting titles and song
book numbers from folder containing SongBeamer files to an XLS file. To be
able to use it icemac.songbeamer has to be installed with the xls extra
like this:
$ pip install "icemac.songbeamer[xls]"

Support UTF-8 encoded SongBeamer files starting with the UTF-8 BOM.
Change license from ZPL to MIT.

0.3 (2018-10-07)

Add support for Python 3.5 to 3.7 and PyPy3.
Drop support for Python 3.2 and 3.3.

0.2.0 (2012-10-31)

Add ability to parse bytes objects.
Sorting keys in export file to be compatible across Python 3.2 and 3.3.

0.1.0 (2012-05-05)

Initial public release.

To do

Implementations

import/export of .col files (schedules)

Open Questions

Are Transpose and Speed actually int values?

Usage

Importing a .sng file
To import a .sng file use the open function in the module
icemac.songbeamer. It expects a filename and path and returns a SNG
instance:

>>> import icemac.songbeamer
>>> import pkg_resources
>>> filename = pkg_resources.resource_filename(
... 'icemac.songbeamer.tests', 'example.sng')
>>> sng = icemac.songbeamer.open(filename)
>>> sng.__class__
<class 'icemac.songbeamer.sng.SNG'>

Alternatively there is a function parse in the same module which parses
bytes (e. g. read from a binary file) into an SNG instance:

>>> with open(filename, 'rb') as file:
... sng = icemac.songbeamer.parse(file.read())
>>> sng.__class__
<class 'icemac.songbeamer.sng.SNG'>

Accessing a file’s data
The SNG instance extends dict so the date is accessible via the usual
python dict API:

>>> from pprint import pprint
>>> pprint(sng)
{'Author': 'me',
'Text': ['La la la', '---', 'Lei lei lei'],
'Version': 3}
>>> sng['Title'] = 'Mÿ šôñg'

The values are stored as numbers resp. strings (text):

>>> sng['Version']
3
>>> sng['Author']
'me'

Exporting a .sng file

>>> from tempfile import TemporaryFile

To export to a .sng file use the export method. It expects a byte stream
(io.BytesIO or open binary file) as argument to write into:

>>> with TemporaryFile() as file:
... sng.export(file)
... _ = file.seek(0)
... pprint(file.readlines())
[b'#Author=me\r\n',
b'#Title=M\xff \x9a\xf4\xf1g\r\n',
b'#Version=3\r\n',
b'---\r\n',
b'La la la\r\n',
b'---\r\n',
b'Lei lei lei']