coalib.bearlib package — coala 0.9.0.dev99999999999999 documentation

# coalib.bearlib package

## Subpackages

- coalib.bearlib.abstractions package
  - Submodules
  - coalib.bearlib.abstractions.ExternalBearWrap module
  - coalib.bearlib.abstractions.Linter module
  - coalib.bearlib.abstractions.SectionCreatable module
  - Module contents
- coalib.bearlib.aspects package
  - Submodules
  - coalib.bearlib.aspects.Metadata module
  - coalib.bearlib.aspects.Redundancy module
  - coalib.bearlib.aspects.base module
  - coalib.bearlib.aspects.docs module
  - coalib.bearlib.aspects.meta module
  - coalib.bearlib.aspects.taste module
  - Module contents
- coalib.bearlib.languages package
  - Subpackages
    - coalib.bearlib.languages.definitions package
      - Submodules
      - coalib.bearlib.languages.definitions.C module
      - coalib.bearlib.languages.definitions.CPP module
      - coalib.bearlib.languages.definitions.CSS module
      - coalib.bearlib.languages.definitions.CSharp module
      - coalib.bearlib.languages.definitions.Java module
      - coalib.bearlib.languages.definitions.JavaScript module
      - coalib.bearlib.languages.definitions.Python module
      - coalib.bearlib.languages.definitions.Vala module
      - Module contents
    - coalib.bearlib.languages.documentation package
      - Submodules
      - coalib.bearlib.languages.documentation.DocstyleDefinition module
      - coalib.bearlib.languages.documentation.DocumentationComment module
      - coalib.bearlib.languages.documentation.DocumentationExtraction module
      - Module contents
  - Submodules
  - coalib.bearlib.languages.Language module
  - coalib.bearlib.languages.LanguageDefinition module
  - Module contents
- coalib.bearlib.naming_conventions package
  - Module contents
- coalib.bearlib.spacing package
  - Submodules
  - coalib.bearlib.spacing.SpacingHelper module
  - Module contents

## Module contents

The bearlib is an optional library designed to ease the task of any Bear. Just as the rest of coala the bearlib is designed to be as easy to use as possible while offering the best possible flexibility.

`coalib.bearlib.` `deprecate_bear`(bear)

  Use this to deprecate a bear. Say we have a bear:

      >>> class SomeBear:
      ...     def run(*args):
      ...         print("I'm running!")

  To change the name from `SomeOldBear` to `SomeBear` you can keep the `SomeOldBear.py` around with those contents:

      >>> @deprecate_bear
      ... class SomeOldBear(SomeBear): pass

  Now let’s run the bear:

      >>> import sys
      >>> logging.basicConfig(stream=sys.stdout, level=logging.DEBUG)
      >>> SomeOldBear().run()
      WARNING:root:The bear SomeOldBear is deprecated. Use SomeBear instead!
      I'm running!

  Parameters: | bear – An old bear class that inherits from the new one (so it gets its methods and can just contain a pass.)
  Returns: | A bear class that warns about deprecation on use.

`coalib.bearlib.` `deprecate_settings`(**depr_args)

  The purpose of this decorator is to allow passing old settings names to bears due to the heavy changes in their names.

      >>> @deprecate_settings(new='old')
      ... def run(new):
      ...     print(new)

  Now we can simply call the bear with the deprecated setting, we’ll get a warning - but it still works!

      >>> import sys
      >>> logging.basicConfig(stream=sys.stdout, level=logging.DEBUG)
      >>> run(old="Hello world!")
      WARNING:root:The setting `old` is deprecated. Please use `new` instead.
      Hello world!
      >>> run(new="Hello world!")
      Hello world!

  This example represents the case where the old setting name needs to be modified to match the new one.

      >>> @deprecate_settings(new=('old', lambda a: a + 'coala!'))
      ... def func(new):
      ...     print(new)

      >>> func(old="Welcome to ")
      WARNING:root:The setting `old` is deprecated. Please use `new` instead.
      Welcome to coala!
      >>> func(new='coala!')
      coala!

  This example represents the case where the old and new settings are provided to the function.

      >>> @deprecate_settings(new='old')
      ... def run(new):
      ...     print(new)
      >>>
      ... run(old="Hello!", new='coala is always written with lowercase `c`.')
      WARNING:root:The setting `old` is deprecated. Please use `new` instead.
      WARNING:root:The value of `old` and `new` are conflicting. `new` will...
      coala is always written with lowercase `c`.
      >>> run(old='Hello!', new='Hello!')
      WARNING:root:The setting `old` is deprecated. Please use `new` instead.
      Hello!

  The metadata for coala has been adjusted as well:

      >>> list(run.__metadata__.non_optional_params.keys())
      ['new']
      >>> list(run.__metadata__.optional_params.keys())
      ['old']

  You cannot deprecate an already deprecated setting. Don’t try. It will introduce non-deterministic errors in your program.

  Parameters: | depr_args – A dictionary of settings as keys and their deprecated names as values.