Skip to main content

Alias Plugin for Beets

Project description

Alias Plugin for Beets

PyPI Status Python Version License

Read the documentation at https://beets-alias.readthedocs.io/ The Ethical Source Principles Contributor Covenant Tests Codecov

pre-commit Ruff codestyle

The alias plugin for beets lets you define command aliases, much like git, and also makes available any beet-prefixed commands in your PATH as well.

Installation

As the beets documentation describes in Other plugins, to use an external plugin like this one, there are two options for installation:

  • Make sure it’s in the Python path (known as sys.path to developers). This just means the plugin has to be installed on your system (e.g., with a setup.py script or a command like pip or easy_install). For example, pip install beets-alias.
  • Set the pluginpath config variable to point to the directory containing the plugin. (See Configuring) This would require cloning or otherwise downloading this repository before adding to the pluginpath.

Configuring

First, enable the alias plugin (see Using Plugins).

To configure the plugin, make an alias: section in your configuration file. The available options are:

  • from_path: Make beet-prefixed commands from PATH available. Default: yes
  • aliases: Map alias names to beets commands or external shell commands. External commands should start with !. This mirrors the behavior of git. An alias may also be defined in an expanded form including help text. An alias may also accept placeholders in the form of {0}, {1} etc. These placeholders will be replaced by the provided arguments with the respective index. {0} will be replaced by parameter 0, {1} with parameter 1 and so on. There's a special placeholder {} which is used for parameters without a matching placeholder (see examples below). This is necessary to enable building aliases for beets commands with a variable number of arguments (like modify). If this placeholder does not exist, the parameters will be appended to the command.

The aliases section may be under alias:, or on its own at top-level.

Example Configuration

alias:
  from_path: yes

aliases:
  singletons: ls singleton:true

  # $ beet get-config alias.aliases.singletons
  get-config: '!sh -c "for arg; do beet config | yq -r \".$arg\"; done" -'

  # Red flags
  empty-artist: ls artist::'^$'
  empty-album: ls album::'^$' singleton:false

  # Simple parameter expansion
  list-live: ls artist:{0} album:{1}
  # command: list-live yello live
  # expands to: beet ls artist:yello album:live

  # Expansion: more placeholders than parameters (command will probably fail)
  list-fail: ls artist:{0} album:{1}
  # command: beet list-fail yello
  # expands to: beet ls artist:yello album:{1}

  # Expansion: more parameters than placeholders, parameters appended
  list-live-2017a: ls year:{2}
  # command: beet list-live-2017a yello live 2017
  # expands to: beet ls year:2017 yello live

  # Expansion: more parameters than placeholders, parameters inserted
  list-live-2017b: ls {} year:{2}
  # command: beet list-live-2017b yello live 2017
  # expands to: beet ls yello live year:2017

  # Expansion: real-world example, modify all live albums by Yello
  set-genre-pop: modify -a {} genre={0}
  # command: beet "Synthie Pop" yello live
  # exapands to: beet modify -a yello live genre="Synthie Pop"

  # Example alias with help and aliases
  recent:
    command: ls added-
    help: List recent items
    aliases: latest recents recent-items

  # Mac-specific
  picard:
    command: '!open -A -a "MusicBrainz Picard"'
    help: Open items in MusicBrainz Picard
    aliases:
      - musicbrainz-picard

Using

Run the beet subcommands created by your aliases configuration. You may also run beet alias to list the defined aliases.

Contributing

Contributions are very welcome. To learn more, see the Contributor Guide.

License

Distributed under the terms of the MIT license, Alias Plugin for Beets is free and open source software. This software prioritizes meeting the criteria of the Ethical Source Principles, though it does not currently utilize an ethical source license.

Issues

If you encounter any problems, please file an issue along with a detailed description.

Credits

Thanks to the project contributors, whose work is much appreciated. This project is a plugin for the beets project, and would not exist without that fantastic project. This project was generated from @cjolowicz's Hypermodern Python Cookiecutter template.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

beets_alias-1.0.1.tar.gz (8.1 kB view details)

Uploaded Source

Built Distribution

beets_alias-1.0.1-py3-none-any.whl (7.9 kB view details)

Uploaded Python 3

File details

Details for the file beets_alias-1.0.1.tar.gz.

File metadata

  • Download URL: beets_alias-1.0.1.tar.gz
  • Upload date:
  • Size: 8.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/5.1.1 CPython/3.12.5

File hashes

Hashes for beets_alias-1.0.1.tar.gz
Algorithm Hash digest
SHA256 3f05a14ca4204e01475a1ca5d89857e9daed32a1cccf9a308f90570a2dbe301f
MD5 ae43fcd40770c9d6740f54980f8e9315
BLAKE2b-256 ac779443176a1662a9569d6420ded8d36bceee9447e2a8d4ca730bcd8cf2c478

See more details on using hashes here.

File details

Details for the file beets_alias-1.0.1-py3-none-any.whl.

File metadata

  • Download URL: beets_alias-1.0.1-py3-none-any.whl
  • Upload date:
  • Size: 7.9 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/5.1.1 CPython/3.12.5

File hashes

Hashes for beets_alias-1.0.1-py3-none-any.whl
Algorithm Hash digest
SHA256 746ae234d47839ec10ffaa744ea874e01ceb0ad119b726994c378dae898a572a
MD5 8ffae2f040a6bfcda1aad9c2b1c0103e
BLAKE2b-256 fbcf20dae83620d4330f6e87fd7ff44db413c703f874b376f2a91980cb002540

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page