traktor-nml-utils


Nametraktor-nml-utils JSON
Version 2.0.6 PyPI version JSON
download
home_pagehttp://github.com/ifischer/traktor-nml-utils
SummaryUtilities to read and write Traktor NML files
upload_time2020-09-01 08:51:17
maintainer
docs_urlNone
authorIngo Fischer
requires_python>=3.7.0
licenseGPL
keywords
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # Traktor NML utils

![Python package](https://github.com/wolkenarchitekt/traktor-nml-utils/workflows/Python%20package/badge.svg?branch=master)

This module contains utilities to parse and modify [Native Instruments Traktor](https://www.native-instruments.com/de/products/traktor/dj-software/traktor-pro-3/) NML files.\
Both Traktor 2.x and Traktor 3.x NML files are supported.

It can parse collection NML files (`$TRAKTOR_DIR/collection.nml`) and history NML files (`$TRAKTOR_DIR/History/history_$DATE.nml`).

All NML attributes are readable and writable using auto-generated dataclasses 
(see `traktor_nml_utils/models`).\
This allows a typesafe way to work with NML files, fully supporting IDE autocompletion:

![alt text](./doc/images/pycharm_completion.gif "PyCharm completion")

While reading should work in 99% cases, writing NML files hasn't been tested thoroughly enough yet, so always 
keep a copy of your NML files.

## Requirements

Because traktor-nml-utils uses `dataclasses`, you need at least Python 3.7.x.

traktor-nml-utils is tested with Traktor 3.3.0, though it should be able to parse
Traktor 2.x NML files as well. Feel free to provide files that cause problems on parsing.  

## Installation

```shell
pip install traktor-nml-utils
```

## Usage

### Get artist, title and rating of all collection entries

```python
from traktor_nml_utils import TraktorCollection
from pathlib import Path

collection = TraktorCollection(path=Path('collection.nml'))

for entry in collection.nml.entry:
    print(entry.artist, entry.title, entry.info.ranking)
```

### Get cuepoint start

```python
entry = collection.nml.entry[0]

for cue_v2 in entry.cue_v2:
    print(cue_v2.start)
```

### Find entry

```python
artist = "Yotto"
title = "Another Riff For The Good Times (Extended Mix)"

entry = [
    entry for entry in collection.nml.entry 
    if entry.artist == artist
    and entry.title == title
][0]
```

### Add cuepoint

```python
from traktor_nml_utils.models.collection import CueV2Type
from traktor_nml_utils.utils import duration_str_to_milliseconds

my_cue = CueV2Type(
    value=None, 
    name='n.n.', 
    displ_order=0, 
    type=0, 
    start=duration_str_to_milliseconds("00:01:00"), 
    len=0.0, 
    repeats=-1, 
    hotcue=1
)
entry.cue_v2.append(my_cue)

# Write XML file
collection.save()
```

## Run tests

Run tests within Docker container:

```shell
make docker-build docker-test
```

Create virtualenv and run tests:

```shell
make virtualenv-create virtualenv-test
```


To test if parsing your own collection/history files with traktor-nml-utils works, 
pass your Traktor directory to pytest:

```shell
pytest --nml-dir="~/traktor3/" tests/test_parser.py::test_parse_nml_files
```  

## How does it work?

### NML file to XSD schema 

Since there is no official XSD available to parse Traktor NML files, an XSD was generated
both for history and collection files using [Apache XMLBeans](https://xmlbeans.apache.org/).

See them in `xml_to_xsd/collection.xsd` and `xml_to_xsd/history.xsd`.

You can regenerate the XSD by putting your own `collection.nml` and `history.nml` overwriting
 the existing ones in `./xml_to_xsd/` and run:
```shell
make xml-to-xsd
```
 
### XSD to Python dataclasses

Using the generated XSD files, Python dataclasses can be generated with [xsdata](https://pypi.org/project/xsdata/).
To update these, run:

```shell
make xsd-to-python
```
 
## Contribution

### Help wanted!
Since the XSD-schema was created from my own Traktor files, the schema might 
not fit for all collection and history files.
In case you have any problems parsing NML files, please report an issue and 
attach the problematic NML file so I can update the schema.
            

Raw data

            {
    "_id": null,
    "home_page": "http://github.com/ifischer/traktor-nml-utils",
    "name": "traktor-nml-utils",
    "maintainer": "",
    "docs_url": null,
    "requires_python": ">=3.7.0",
    "maintainer_email": "",
    "keywords": "",
    "author": "Ingo Fischer",
    "author_email": "mail@ingofischer.de",
    "download_url": "https://files.pythonhosted.org/packages/ae/4a/547468d8d3c7aca9aa2d78fa56246a008b05d33e53f720baa75090f62fc3/traktor-nml-utils-2.0.6.tar.gz",
    "platform": "",
    "description": "# Traktor NML utils\n\n![Python package](https://github.com/wolkenarchitekt/traktor-nml-utils/workflows/Python%20package/badge.svg?branch=master)\n\nThis module contains utilities to parse and modify [Native Instruments Traktor](https://www.native-instruments.com/de/products/traktor/dj-software/traktor-pro-3/) NML files.\\\nBoth Traktor 2.x and Traktor 3.x NML files are supported.\n\nIt can parse collection NML files (`$TRAKTOR_DIR/collection.nml`) and history NML files (`$TRAKTOR_DIR/History/history_$DATE.nml`).\n\nAll NML attributes are readable and writable using auto-generated dataclasses \n(see `traktor_nml_utils/models`).\\\nThis allows a typesafe way to work with NML files, fully supporting IDE autocompletion:\n\n![alt text](./doc/images/pycharm_completion.gif \"PyCharm completion\")\n\nWhile reading should work in 99% cases, writing NML files hasn't been tested thoroughly enough yet, so always \nkeep a copy of your NML files.\n\n## Requirements\n\nBecause traktor-nml-utils uses `dataclasses`, you need at least Python 3.7.x.\n\ntraktor-nml-utils is tested with Traktor 3.3.0, though it should be able to parse\nTraktor 2.x NML files as well. Feel free to provide files that cause problems on parsing.  \n\n## Installation\n\n```shell\npip install traktor-nml-utils\n```\n\n## Usage\n\n### Get artist, title and rating of all collection entries\n\n```python\nfrom traktor_nml_utils import TraktorCollection\nfrom pathlib import Path\n\ncollection = TraktorCollection(path=Path('collection.nml'))\n\nfor entry in collection.nml.entry:\n    print(entry.artist, entry.title, entry.info.ranking)\n```\n\n### Get cuepoint start\n\n```python\nentry = collection.nml.entry[0]\n\nfor cue_v2 in entry.cue_v2:\n    print(cue_v2.start)\n```\n\n### Find entry\n\n```python\nartist = \"Yotto\"\ntitle = \"Another Riff For The Good Times (Extended Mix)\"\n\nentry = [\n    entry for entry in collection.nml.entry \n    if entry.artist == artist\n    and entry.title == title\n][0]\n```\n\n### Add cuepoint\n\n```python\nfrom traktor_nml_utils.models.collection import CueV2Type\nfrom traktor_nml_utils.utils import duration_str_to_milliseconds\n\nmy_cue = CueV2Type(\n    value=None, \n    name='n.n.', \n    displ_order=0, \n    type=0, \n    start=duration_str_to_milliseconds(\"00:01:00\"), \n    len=0.0, \n    repeats=-1, \n    hotcue=1\n)\nentry.cue_v2.append(my_cue)\n\n# Write XML file\ncollection.save()\n```\n\n## Run tests\n\nRun tests within Docker container:\n\n```shell\nmake docker-build docker-test\n```\n\nCreate virtualenv and run tests:\n\n```shell\nmake virtualenv-create virtualenv-test\n```\n\n\nTo test if parsing your own collection/history files with traktor-nml-utils works, \npass your Traktor directory to pytest:\n\n```shell\npytest --nml-dir=\"~/traktor3/\" tests/test_parser.py::test_parse_nml_files\n```  \n\n## How does it work?\n\n### NML file to XSD schema \n\nSince there is no official XSD available to parse Traktor NML files, an XSD was generated\nboth for history and collection files using [Apache XMLBeans](https://xmlbeans.apache.org/).\n\nSee them in `xml_to_xsd/collection.xsd` and `xml_to_xsd/history.xsd`.\n\nYou can regenerate the XSD by putting your own `collection.nml` and `history.nml` overwriting\n the existing ones in `./xml_to_xsd/` and run:\n```shell\nmake xml-to-xsd\n```\n \n### XSD to Python dataclasses\n\nUsing the generated XSD files, Python dataclasses can be generated with [xsdata](https://pypi.org/project/xsdata/).\nTo update these, run:\n\n```shell\nmake xsd-to-python\n```\n \n## Contribution\n\n### Help wanted!\nSince the XSD-schema was created from my own Traktor files, the schema might \nnot fit for all collection and history files.\nIn case you have any problems parsing NML files, please report an issue and \nattach the problematic NML file so I can update the schema.",
    "bugtrack_url": null,
    "license": "GPL",
    "summary": "Utilities to read and write Traktor NML files",
    "version": "2.0.6",
    "split_keywords": [],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "1002b658a59739e2692efb59c5f7eed6",
                "sha256": "9baae20d6bbb2996403b277d8e2f6edd605c703e58cc707368888cc0bd7a0f2c"
            },
            "downloads": -1,
            "filename": "traktor-nml-utils-2.0.6.tar.gz",
            "has_sig": false,
            "md5_digest": "1002b658a59739e2692efb59c5f7eed6",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.7.0",
            "size": 9764,
            "upload_time": "2020-09-01T08:51:17",
            "upload_time_iso_8601": "2020-09-01T08:51:17.980278Z",
            "url": "https://files.pythonhosted.org/packages/ae/4a/547468d8d3c7aca9aa2d78fa56246a008b05d33e53f720baa75090f62fc3/traktor-nml-utils-2.0.6.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2020-09-01 08:51:17",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "github_user": null,
    "github_project": "ifischer",
    "error": "Could not fetch GitHub repository",
    "lcname": "traktor-nml-utils"
}
        
Elapsed time: 0.14113s