diff --git a/beetsplug/zero.py b/beetsplug/zero.py index b97c37bcd..561430ddc 100644 --- a/beetsplug/zero.py +++ b/beetsplug/zero.py @@ -42,7 +42,7 @@ class ZeroPlugin(BeetsPlugin): self.config.add({ 'fields': [], 'keep_fields': [], - 'update_database': False + 'update_database': False, }) self.patterns = {} @@ -51,7 +51,7 @@ class ZeroPlugin(BeetsPlugin): if self.config['fields']: self.validate_config('fields') for field in self.config['fields'].as_str_seq(): - self.write_patterns(field) + self.set_pattern(field) elif self.config['keep_fields']: self.validate_config('keep_fields') @@ -59,7 +59,7 @@ class ZeroPlugin(BeetsPlugin): for field in MediaFile.fields(): if field in self.config['keep_fields'].as_str_seq(): continue - self.write_patterns(field) + self.set_pattern(field) # These fields should be preserved for key in ('id', 'path', 'album_id'): @@ -79,7 +79,10 @@ class ZeroPlugin(BeetsPlugin): u'it would be dangerous', field) continue - def write_patterns(self, field): + def set_pattern(self, field): + """Set a field in `self.patterns` to a string list corresponding to + the configuration, or `True` if the field has no specific configuration. + """ try: self.patterns[field] = self.config[field].as_str_seq() except confit.NotFoundError: diff --git a/docs/plugins/zero.rst b/docs/plugins/zero.rst index 360c737a5..cc70e6675 100644 --- a/docs/plugins/zero.rst +++ b/docs/plugins/zero.rst @@ -2,10 +2,8 @@ Zero Plugin =========== The ``zero`` plugin allows you to null fields in files' metadata tags. Fields -can be nulled unconditionally or conditioned on a pattern match. It works in -two independent modes - blacklist and whitelist. You can only choose one option, -however blacklist is the default. For example, the plugin can strip useless -comments like "ripped by MyGreatRipper." +can be nulled unconditionally or conditioned on a pattern match. For example, +the plugin can strip useless comments like "ripped by MyGreatRipper." To use the ``zero`` plugin, enable the plugin in your configuration (see :ref:`using-plugins`). @@ -20,9 +18,9 @@ fields to nullify and the conditions for nullifying them: get the list of all available fields by running ``beet fields``. In addition, the ``images`` field allows you to remove any images embedded in the media file. -* Set ``keep_fields`` respectively to list of fields that plugin should - preserve. That way ``zero`` cleans anything other than fields written in this - option. +* Set ``keep_fields`` to *invert* the logic of the plugin. Only these fields + will be kept; other fields will be removed. Remember to set only + ``fields`` or ``keep_fields``, not both! * To conditionally filter a field, use ``field: [regexp, regexp]`` to specify regular expressions. * By default this plugin only affects files' tags ; the beets database is left @@ -36,6 +34,10 @@ For example:: genre: [rnb, 'power metal'] update_database: true +The plugin can work in one of two modes. The first mode, the default, +is a blacklist, where you choose the tags you want to remove. The second mode +is a whitelist where you instead specify the tags you want to keep. + If a custom pattern is not defined for a given field, the field will be nulled unconditionally.