Merge pull request #1945 from beetbox/export-plugin

Export plugin: Export data from queries to a json

beetsplug/export.py

@@ -0,0 +1,151 @@
+# -*- coding: utf-8 -*-
+# This file is part of beets.
+#
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+#
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+
+"""Exports data from beets
+"""
+
+from __future__ import division, absolute_import, print_function
+
+import sys
+import json
+import codecs
+
+from datetime import datetime, date
+from beets.plugins import BeetsPlugin
+from beets import ui
+from beets import mediafile
+from beetsplug.info import make_key_filter, library_data, tag_data
+
+
+class ExportEncoder(json.JSONEncoder):
+    """Deals with dates because JSON doesn't have a standard"""
+    def default(self, o):
+        if isinstance(o, datetime) or isinstance(o, date):
+            return o.isoformat()
+        return json.JSONEncoder.default(self, o)
+
+
+class ExportPlugin(BeetsPlugin):
+
+    def __init__(self):
+        super(ExportPlugin, self).__init__()
+
+        self.config.add({
+            'default_format': 'json',
+            'json': {
+                # json module formatting options
+                'formatting': {
+                    'ensure_ascii': False,
+                    'indent': 4,
+                    'separators': (',', ': '),
+                    'sort_keys': True
+                }
+            },
+            # TODO: Use something like the edit plugin
+            # 'item_fields': []
+        })
+
+    def commands(self):
+        # TODO: Add option to use albums
+
+        cmd = ui.Subcommand('export', help=u'export data from beets')
+        cmd.func = self.run
+        cmd.parser.add_option(
+            u'-l', u'--library', action='store_true',
+            help=u'show library fields instead of tags',
+        )
+        cmd.parser.add_option(
+            u'--append', action='store_true', default=False,
+            help=u'if should append data to the file',
+        )
+        cmd.parser.add_option(
+            u'-i', u'--include-keys', default=[],
+            action='append', dest='included_keys',
+            help=u'comma separated list of keys to show',
+        )
+        cmd.parser.add_option(
+            u'-o', u'--output',
+            help=u'path for the output file. If not given, will print the data'
+        )
+        return [cmd]
+
+    def run(self, lib, opts, args):
+
+        file_path = opts.output
+        file_format = self.config['default_format'].get(str)
+        file_mode = 'a' if opts.append else 'w'
+        format_options = self.config[file_format]['formatting'].get(dict)
+
+        export_format = ExportFormat.factory(
+            file_format, **{
+                'file_path': file_path,
+                'file_mode': file_mode
+            }
+        )
+
+        items = []
+        data_collector = library_data if opts.library else tag_data
+
+        included_keys = []
+        for keys in opts.included_keys:
+            included_keys.extend(keys.split(','))
+        key_filter = make_key_filter(included_keys)
+
+        for data_emitter in data_collector(lib, ui.decargs(args)):
+            try:
+                data, item = data_emitter()
+            except (mediafile.UnreadableFileError, IOError) as ex:
+                self._log.error(u'cannot read file: {0}', ex)
+                continue
+
+            data = key_filter(data)
+            items += [data]
+
+        export_format.export(items, **format_options)
+
+
+class ExportFormat(object):
+    """The output format type"""
+
+    @classmethod
+    def factory(self, type, **kwargs):
+        if type == "json":
+            if kwargs['file_path']:
+                return JsonFileFormat(**kwargs)
+            else:
+                return JsonPrintFormat()
+        raise NotImplementedError()
+
+    def export(self, data, **kwargs):
+        raise NotImplementedError()
+
+
+class JsonPrintFormat(ExportFormat):
+    """Outputs to the console"""
+
+    def export(self, data, **kwargs):
+        json.dump(data, sys.stdout, cls=ExportEncoder, **kwargs)
+
+
+class JsonFileFormat(ExportFormat):
+    """Saves in a json file"""
+
+    def __init__(self, file_path, file_mode=u'w', encoding=u'utf-8'):
+        self.path = file_path
+        self.mode = file_mode
+        self.encoding = encoding
+
+    def export(self, data, **kwargs):
+        with codecs.open(self.path, self.mode, self.encoding) as f:
+            json.dump(data, f, cls=ExportEncoder, **kwargs)

docs/changelog.rst

@@ -15,6 +15,8 @@ New features:
   for a Microsoft Azure Marketplace free account. Thanks to :user:`Kraymer`.
 * :doc:`/plugins/fetchart`: Album art can now be fetched from `fanart.tv`_.
   Albums are matched using the ``mb_releasegroupid`` tag.
+* :doc:`/plugins/export`: A new plugin to export the data from queries to a
+  json format. Thanks to :user:`GuilhermeHideki`.
 
 .. _fanart.tv: https://fanart.tv/
 

docs/plugins/export.rst

@@ -0,0 +1,70 @@
+Export Plugin
+=============
+
+The ``export`` plugin lets you get data from the items and export the content to
+a ``json`` file.
+
+Configuration
+-------------
+To configure the plugin, make a ``export:`` section in your configuration
+file. The default options are::
+
+  export:
+    default_format: json
+    json:
+      formatting:
+        ensure_ascii: False
+        indent: 4
+        separators: [',' , ': ']
+        sort_keys: true
+
+- **default_format**: Choose the format of the exported content.
+  Supports json only for now.
+
+Each format have their own options.
+
+The ``json`` formatting uses the `json`_ standard library options.
+Using custom options overwrites all options at the same level.
+The default options used here are:
+
+- **ensure_ascii**: All non-ASCII characters are escaped with `\uXXXX`, if true.
+
+- **indent**: The number of spaces for indentation.
+
+- **separators**: A ``(item_separator, dict_separator)`` tuple
+
+- **sort_keys**: Sorts the keys of the json
+
+.. _json: https://docs.python.org/2/library/json.html#basic-usage
+
+Using
+-----
+
+Enable the ``export`` plugin (see :ref:`using-plugins` for help) and then add a
+``export`` section to your :doc:`configuration file </reference/config>`
+
+To use, you can enter a :doc:`query </reference/query>` to get the data from
+your library::
+
+    $ beet export beatles
+
+If you just want to see specific properties you can use the
+``--include-keys`` option to filter them. The argument is a
+comma-separated list of simple glob patterns where ``*`` matches any
+string. For example::
+
+    $ beet export -i 'title,mb*' beatles
+
+Will only show the ``title`` property and all properties starting with
+``mb``. You can add the ``-i`` option multiple times to the command
+line.
+
+Additional command-line options include:
+
+* ``--library`` or ``-l``: Show data from the library database instead of the
+  files' tags.
+
+* ``--output`` or ``-o``: Path for an output file. If not informed, will print
+  the data in the console.
+
+* ``--append``: Appends the data to the file instead of writing.

docs/plugins/index.rst

@@ -44,6 +44,7 @@ Each plugin has its own set of options that can be defined in a section bearing
    edit
    embedart
    embyupdate
+   export
    fetchart
    fromfilename
    ftintitle
@@ -161,6 +162,7 @@ Miscellaneous
 * :doc:`convert`: Transcode music and embed album art while exporting to
   a different directory.
 * :doc:`duplicates`: List duplicate tracks or albums.
+* :doc:`export`: Export data from queries to a format.
 * :doc:`fuzzy`: Search albums and tracks with fuzzy string matching.
 * :doc:`ihate`: Automatically skip albums and tracks during the import process.
 * :doc:`info`: Print music files' tags to the console.