{ "info": { "author": "Jon Grace-Cox", "author_email": "jongracecox@gmail.com", "bugtrack_url": null, "classifiers": [ "License :: OSI Approved :: MIT License" ], "description": "\nanybadge\n========\n\nPython project for generating badges for your projects\n\n\n.. image:: https://badge.fury.io/py/anybadge.svg\n :target: https://pypi.org/project/anybadge\n :alt: pypi package\n\n\n.. image:: https://api.travis-ci.org/jongracecox/anybadge.svg?branch=master\n :target: https://travis-ci.org/jongracecox/anybadge\n :alt: build status\n\n\n.. image:: https://img.shields.io/pypi/dm/anybadge.svg\n :target: https://pypistats.org/packages/anybadge\n :alt: downloads\n\n\n.. image:: https://img.shields.io/github/last-commit/jongracecox/anybadge.svg\n :target: https://github.com/jongracecox/anybadge/commits/master\n :alt: GitHub last commit\n\n\n.. image:: https://img.shields.io/github/license/jongracecox/anybadge.svg\n :target: https://github.com/jongracecox/anybadge/blob/master/LICENSE\n :alt: GitHub\n\n\n.. image:: https://img.shields.io/github/stars/jongracecox/anybadge.svg?style=social\n :target: https://github.com/jongracecox/anybadge/stargazers\n :alt: GitHub stars\n\n\nOverview\n--------\n\n``anybadge`` can be used to add badge generation to your Python projects,\nand also provides a command line interface.\n\nThis utility can be used to generate .svg badge images, using configurable\nthresholds for coloring the badges based on the badge value. Many badge\ngeneration tools just provide the ability to specify the color of badge.\n``anybadge`` allows you to specify the label, badge value, and color, but\nit also allows you to specify a set of thresholds that can be used to\nselect a color based on the badge value.\n\n``anybadge`` may be useful for companies developing internally, or any time\nmaking calls to external badge services is not possible, or undesirable.\nIn this situation using ``anybadge`` will be easier than running your own\ninternal badge service.\n\nThe package can be imported into your python code, or run direct from the\ncommand line.\n\nDemo\n----\n\nYou can find a `repl.it demo here `_.\nThis will allow you to see what the package can do and play with it to test outputs.\n\nBasic usage\n-----------\n\nCommand line\n^^^^^^^^^^^^\n\nAs an example, if you want to produce a pylint badge, you may run ``anybadge``\nfrom the command line like this:\n\n.. code-block:: bash\n\n anybadge -l pylint -v 2.22 -f pylint.svg 2=red 4=orange 8=yellow 10=green\n\nThis would result in a badge like this:\n\n\n.. image:: https://cdn.rawgit.com/jongracecox/anybadge/master/examples/pylint.svg\n :target: https://cdn.rawgit.com/jongracecox/anybadge/master/examples/pylint.svg\n :alt: pylint\n\n\nIn this example the label is set to \"pylint\", the value \"2.22\", and an\noutput file called \"pylint.svg\". The thresholds are provided in pairs\nof ``=color`` Values can be integer or floats for ranges, and\nstring values are also supported.\n\nPython\n^^^^^^\n\nHere is the same example implemented in Python code:\n\n.. code-block:: python\n\n import anybadge\n\n # Define thresholds: <2=red, <4=orange <8=yellow <10=green\n thresholds = {2: 'red',\n 4: 'orange',\n 6: 'yellow',\n 10: 'green'}\n\n badge = anybadge.Badge('pylint', 2.22, thresholds=thresholds)\n\n badge.write_badge('pylint.svg')\n\nInstallation\n------------\n\n``anybadge`` is available in PyPi at https://pypi.python.org/pypi/anybadge\n\nYou can install the latest release of ``anybadge`` using ``pip``\\ :\n\n.. code-block:: bash\n\n pip install anybadge\n\nThis will install the Python package, and also make ``anybadge`` available\nas a command line utility.\n\nGetting help\n------------\n\nTo get help from the command line utility, just run:\n\n.. code-block:: bash\n\n anybadge --help\n\nCommand line usage\n------------------\n\nOutput\n^^^^^^\n\nRunning the utility with the ``--file`` option will result in the .svg image being\nwritten to file. Without the ``--file`` option the ``.svg`` file content will be\nwritten to stdout, so can be redirected to a file.\n\nThresholds\n^^^^^^^^^^\n\nSome thresholds have been built in to save time. To use these thresholds you\ncan simply specify the template name instead of threshold value/color pairs.\n\n.. code-block::\n\n anybadge --value= --file= \n\nFor example:\n\n.. code-block:: bash\n\n anybadge --value=2.22 --file=pylint.svg pylint\n\nExamples\n^^^^^^^^\n\nPylint using template\n~~~~~~~~~~~~~~~~~~~~~\n\n.. code-block::\n\n anybadge --value=2.22 --file=pylint.svg pylint\n\n\n.. image:: https://cdn.rawgit.com/jongracecox/anybadge/master/examples/pylint.svg\n :target: https://cdn.rawgit.com/jongracecox/anybadge/master/examples/pylint.svg\n :alt: pylint\n\n\nPylint using arguments\n~~~~~~~~~~~~~~~~~~~~~~\n\n.. code-block::\n\n anybadge -l pylint -v 2.22 -f pylint.svg 2=red 4=orange 8=yellow 10=green\n\n\n.. image:: https://cdn.rawgit.com/jongracecox/anybadge/master/examples/pylint.svg\n :target: https://cdn.rawgit.com/jongracecox/anybadge/master/examples/pylint.svg\n :alt: pylint\n\n\nCoverage using template\n~~~~~~~~~~~~~~~~~~~~~~~\n\n.. code-block::\n\n anybadge --value=65 --file=coverage.svg coverage\n\n\n.. image:: https://cdn.rawgit.com/jongracecox/anybadge/master/examples/coverage.svg\n :target: https://cdn.rawgit.com/jongracecox/anybadge/master/examples/coverage.svg\n :alt: pylint\n\n\nPipeline, using labeled colors\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n.. code-block::\n\n anybadge --label=pipeline --value=passing --file=pipeline.svg passing=green failing=red\n\n\n.. image:: https://cdn.rawgit.com/jongracecox/anybadge/master/examples/pipeline.svg\n :target: https://cdn.rawgit.com/jongracecox/anybadge/master/examples/pipeline.svg\n :alt: pylint\n\n\nBadge with fixed color\n~~~~~~~~~~~~~~~~~~~~~~\n\n.. code-block::\n\n anybadge --label=awesomeness --value=\"110%\" --file=awesomeness.svg --color=#97CA00\n\n\n.. image:: https://cdn.rawgit.com/jongracecox/anybadge/master/examples/awesomeness.svg\n :target: https://cdn.rawgit.com/jongracecox/anybadge/master/examples/awesomeness.svg\n :alt: pylint\n\n\nOptions\n^^^^^^^\n\nThese are the command line options:\n\n.. code-block::\n\n positional arguments:\n args Pairs of =. For example 2=red 4=orange\n 6=yellow 8=good. Read this as \"Less than 2 = red, less\n than 4 = orange...\".\n\n optional arguments:\n -h, --help show this help message and exit\n -l LABEL, --label LABEL\n The badge label.\n -v VALUE, --value VALUE\n The badge value.\n -m VALUE_FORMAT, --value-format VALUE_FORMAT\n Formatting string for value (e.g. \"%.2f\" for 2dp\n floats)\n -c COLOR, --color COLOR\n For fixed color badges use --colorto specify the badge\n color.\n -p PREFIX, --prefix PREFIX\n Optional prefix for value.\n -s SUFFIX, --suffix SUFFIX\n Optional suffix for value.\n -d PADDING, --padding PADDING\n Number of characters to pad on either side of the\n badge text.\n -n FONT, --font FONT \"DejaVu Sans,Verdana,Geneva,sans-serif\"\n -z FONT_SIZE, --font-size FONT_SIZE\n Font size.\n -t TEMPLATE, --template TEMPLATE\n Location of alternative template .svg file.\n -u, --use-max Use the maximum threshold color when the value exceeds\n the maximum threshold.\n -f FILE, --file FILE Output file location.\n -o, --overwrite Overwrite output file if it already exists.\n -r TEXT_COLOR, --text-color TEXT_COLOR\n Text color. Single value affects both labeland value\n colors. A comma separated pair affects label and value\n text respectively.\n\n Examples\n --------\n\n Here are some usage specific command line examples that may save time on defining\n thresholds.\n\n Pylint::\n\n anybadge.py --value=2.22 --file=pylint.svg pylint\n anybadge.py --label=pylint --value=2.22 --file=pylint.svg 2=red 4=orange 8=yellow 10=green\n\n Coverage::\n\n anybadge.py --value=65 --file=coverage.svg coverage\n anybadge.py --label=coverage --value=65 --suffix='%%' --file=coverage.svg 50=red 60=orange 80=yellow 100=green\n\n CI Pipeline::\n\n anybadge.py --label=pipeline --value=passing --file=pipeline.svg passing=green failing=red\n\n Python usage\n ============\n Here is the output of ``help(anybadge)``::\n\n Help on module anybadge:\n\n NAME\n anybadge - anybadge\n\n DESCRIPTION\n A Python module for generating badges for your projects, with a focus on\n simplicity and flexibility.\n\n CLASSES\n builtins.object\n Badge\n\n class Badge(builtins.object)\n | Badge(label, value, font_name='DejaVu Sans,Verdana,Geneva,sans-serif', font_size=11, num_padding_chars=0.5, template='\\n\\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n {{ label }}\\n {{ label }}\\n \\n \\n {{ value }}\\n {{ value }}\\n \\n', value_prefix='', value_suffix='', thresholds=None, default_color='#4c1', use_max_when_value_exceeds=True, value_format=None, text_color='#fff')\n | \n | Badge class used to generate badges.\n | \n | Examples:\n | \n | Create a simple green badge:\n | \n | >>> badge = Badge('label', 123, default_color='green')\n | \n | Write a badge to file, overwriting any existing file:\n | \n | >>> badge = Badge('label', 123, default_color='green')\n | >>> badge.write_badge('demo.svg', overwrite=True)\n | \n | Here are a number of examples showing thresholds, since there\n | are certain situations that may not be obvious:\n | \n | >>> badge = Badge('pipeline', 'passing', thresholds={'passing': 'green', 'failing': 'red'})\n | >>> badge.badge_color\n | 'green'\n | \n | 2.32 is not <2\n | 2.32 is < 4, so 2.32 yields orange\n | >>> badge = Badge('pylint', 2.32, thresholds={2: 'red',\n | ... 4: 'orange',\n | ... 8: 'yellow',\n | ... 10: 'green'})\n | >>> badge.badge_color\n | 'orange'\n | \n | 8 is not <8\n | 8 is <4, so 8 yields orange\n | >>> badge = Badge('pylint', 8, thresholds={2: 'red',\n | ... 4: 'orange',\n | ... 8: 'yellow',\n | ... 10: 'green'})\n | >>> badge.badge_color\n | 'green'\n | \n | 10 is not <8, but use_max_when_value_exceeds defaults to\n | True, so 10 yields green\n | >>> badge = Badge('pylint', 11, thresholds={2: 'red',\n | ... 4: 'orange',\n | ... 8: 'yellow',\n | ... 10: 'green'})\n | >>> badge.badge_color\n | 'green'\n | \n | 11 is not <10, and use_max_when_value_exceeds is set to\n | False, so 11 yields the default color '#4c1'\n | >>> badge = Badge('pylint', 11, use_max_when_value_exceeds=False,\n | ... thresholds={2: 'red', 4: 'orange', 8: 'yellow',\n | ... 10: 'green'})\n | >>> badge.badge_color\n | '#4c1'\n | \n | Methods defined here:\n | \n | __init__(self, label, value, font_name='DejaVu Sans,Verdana,Geneva,sans-serif', font_size=11, num_padding_chars=0.5, template='\\n\\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n {{ label }}\\n {{ label }}\\n \\n \\n {{ value }}\\n {{ value }}\\n \\n', value_prefix='', value_suffix='', thresholds=None, default_color='#4c1', use_max_when_value_exceeds=True, value_format=None, text_color='#fff')\n | Constructor for Badge class.\n | \n | get_text_width(self, text)\n | Return the width of text.\n | \n | Args:\n | text(str): Text to get the pixel width of.\n | \n | Returns:\n | int: Pixel width of the given text based on the badges selected font.\n | \n | This implementation assumes a fixed font of:\n | \n | font-family=\"DejaVu Sans,Verdana,Geneva,sans-serif\" font-size=\"11\"\n | >>> badge = Badge('x', 1, font_name='DejaVu Sans,Verdana,Geneva,sans-serif', font_size=11)\n | >>> badge.get_text_width('pylint')\n | 34\n | \n | write_badge(self, file_path, overwrite=False)\n | Write badge to file.\n | \n | ----------------------------------------------------------------------\n | Data descriptors defined here:\n | \n | __dict__\n | dictionary for instance variables (if defined)\n | \n | __weakref__\n | list of weak references to the object (if defined)\n | \n | badge_color\n | Badge color based on the configured thresholds.\n | \n | Returns: str\n | \n | badge_color_code\n | Return the color code for the badge.\n | \n | Returns: str\n | \n | badge_svg_text\n | The badge SVG text.\n | \n | Returns: str\n | \n | badge_width\n | The total width of badge.\n | \n | Returns: int\n | \n | Examples:\n | \n | >>> badge = Badge('pylint', '5')\n | >>> badge.badge_width\n | 103\n | \n | color_split_position\n | The SVG x position where the color split should occur.\n | \n | Returns: int\n | \n | font_width\n | Return the width multiplier for a font.\n | \n | Returns:\n | int: Maximum pixel width of badges selected font.\n | \n | Example:\n | \n | >>> Badge(label='x', value='1').font_width\n | 10\n | \n | label_anchor\n | The SVG x position of the middle anchor for the label text.\n | \n | Returns: float\n | \n | label_anchor_shadow\n | The SVG x position of the label shadow anchor.\n | \n | Returns: float\n | \n | label_width\n | The SVG width of the label text.\n | \n | Returns: int\n | \n | value_anchor\n | The SVG x position of the middle anchor for the value text.\n | \n | Returns: float\n | \n | value_anchor_shadow\n | The SVG x position of the value shadow anchor.\n | \n | Returns: float\n | \n | value_is_float\n | Identify whether the value text is a float.\n | \n | Returns: bool\n | \n | value_is_int\n | Identify whether the value text is an int.\n | \n | Returns: bool\n | \n | value_type\n | The Python type associated with the value.\n | \n | Returns: type\n | \n | value_width\n | The SVG width of the value text.\n | \n | Returns: int\n\n FUNCTIONS\n main()\n Generate a badge based on command line arguments.\n\n parse_args()\n Parse the command line arguments.\n\n DATA\n BADGE_TEMPLATES = {'coverage': {'label': 'coverage', 'suffix': '%', 't...\n COLORS = {'green': '#4c1', 'lightgrey': '#9f9f9f', 'orange': '#fe7d37'...\n DEFAULT_COLOR = '#4c1'\n DEFAULT_FONT = 'DejaVu Sans,Verdana,Geneva,sans-serif'\n DEFAULT_FONT_SIZE = 11\n DEFAULT_TEXT_COLOR = '#fff'\n FONT_WIDTHS = {'DejaVu Sans,Verdana,Geneva,sans-serif': {11: 10}}\n NUM_PADDING_CHARS = 0.5\n TEMPLATE_SVG = '\\n