coala Documentation Release 0.5.2
The coala Developers
June 17, 2016
Home
1 coala Installation 1 1.1 System wide installation...... 1 1.2 Installing inside a virtualenv...... 2 1.3 Installing coala from source...... 2 1.4 Dependencies...... 3
2 The .coafile Specification 5 2.1 Naming, Scope and Location...... 5 2.2 Setting Inheritance...... 5
3 Glob - Extended unix style pathname expansion7 3.1 Syntax...... 7 3.2 Examples...... 7
4 Exit Codes 11
5 External APIs 13 5.1 DBus...... 13
6 Git Hooks 15 6.1 Pre Commit Hooks...... 15
7 coala Tutorial 17 7.1 Prerequisites...... 17 7.2 Get Some Code...... 17 7.3 Let’s Start!...... 17 7.4 Sections...... 18 7.5 Auto-applying results...... 19 7.6 Setting Inheritance...... 19 7.7 Ignoring Issues...... 20 7.8 Enabling/Disabling Sections...... 21 7.9 Show bears’ information...... 21 7.10 Integrating coala into Your Project...... 21 7.11 Continuing the Journey...... 22
8 Guide to Write a Bear 23 8.1 What is a bear?...... 23 8.2 A Hello World Bear...... 23 8.3 Communicating with the User...... 24
i 8.4 Results...... 25
9 Linter Bears 27 9.1 Why is This Useful?...... 27 9.2 What do we Need?...... 27 9.3 Writing the Bear...... 27 9.4 Adding Settings to our Bear...... 29 9.5 Right place for ‘{filename}’...... 30 9.6 Finished Bear...... 30 9.7 Running and Testing our Bear...... 31
10 Bears That Can Suggest And Make Corrections 33
11 Git tutorial 35 11.1 How to install Git...... 35 11.2 Getting started with coala...... 35 11.3 Grabbing coala on your local machine...... 35 11.4 Getting to work...... 36 11.5 Creating a new branch...... 36 11.6 Checking your work...... 36 11.7 Adding the files and commiting...... 36 11.8 Pushing the commit...... 37 11.9 Creating a Pull Request...... 37 11.10 Follow-up...... 37 11.11 Keeping your fork in sync...... 38 11.12 Squashing your commits...... 38 11.13 Useful Git commands...... 39
12 Welcome to the Newcomers guide! 41 12.1 Meet the community!...... 41 12.2 Start working...... 41 12.3 Get help with git...... 41 12.4 Start working...... 41 12.5 Things to do before pushing...... 42 12.6 Sending your changes...... 42 12.7 Creating a Pull Request...... 42 12.8 What to do after creating a PR...... 42
13 Getting Involved 45
14 Codestyle for coala 47 14.1 Additional Style Guidelines...... 47
15 Introduction 49 15.1 What Makes a Good Commit...... 49 15.2 How to Write Good Commit Messages...... 49 15.3 Why Do We Need Good Commits?...... 51
16 Testing 53 16.1 Executing our Tests...... 53 16.2 Using test coverage...... 53
17 Reviewing 55 17.1 Review Process...... 55 17.2 Continous Integration...... 55
ii 17.3 Reviewing Commits...... 55
18 Introduction 57 18.1 Actually Writing a Test...... 57 18.2 setUp() and tearDown() ...... 59 18.3 Assertions...... 59 18.4 Kickstart...... 60
19 Writing Documentation 63
20 Coverage Installation Hints for OSX Users: 65 20.1 1. Make sure you have installed Xcode and Homebrew...... 65 20.2 2. Install Python3...... 65 20.3 3. Create Virtual environments with pyvenv...... 65 20.4 4. Virtualenvwrapper with Python 3:...... 65 20.5 Finally!...... 66
21 A Hitchhiker’s Guide to Git(1): Genesis 67 21.1 Introduction...... 67 21.2 What’s Git for Anyway?...... 69 21.3 Setting Up Git...... 69 21.4 Create a Repository...... 69 21.5 Creating a God Commit...... 70 21.6 Inspecting What Happened...... 72 21.7 Creating a Child Commit...... 73 21.8 A Glance At Our History...... 74 21.9 Configuring Git Even Better...... 75 21.10 Conclusion...... 76
22 coalib 77 22.1 coalib package...... 77
23 What is coala? 137
24 What do I get? 139 24.1 As a User...... 139 24.2 As a Developer...... 139
25 Status and Stability of the Project 141
26 Indices and tables 143
Python Module Index 145
iii iv CHAPTER 1
coala Installation
This document contains information on how to install coala. Supported platforms are Linux and Windows. coala is known to work on OS X as well. coala is tested against CPython 3.3, 3.4 and 3.5. In order to run coala you need to install Python. It is recommended, that you install Python3 >= 3.3 from http://www.python.org. The easiest way to install coala is using pip (Pip Installs Packages). If you don’t already have pip, you can install it like described on https://pip.pypa.io/en/stable/installing.html. Note that pip is shipped with recent python versions by default.
1.1 System wide installation
The simplest way to install coala is to do it system-wide. But, This is generally discouraged in favor or using a virtualenv. To install the latest most stable version of coala and supported bears system-wide, use: $ pip3 install coala-bears
Note: For this and all future steps, some steps require root access (also known as administrative privileges in Win- dows). Unix based (Mac, Linux) - This can be achieved by using sudo in front of the command sudo command_name instead of command_name Windows - The easiest way on windows is to start a command prompt as an administrator and start setup.py.
To install the nightly build from our master branch, you can do: $ pip3 install coala-bears --pre
To install only coala (without any bears), you can do: $ pip3 install coala
With --pre you can install the nightly build of the coala base without bears.
1 coala Documentation, Release 0.5.2
1.2 Installing inside a virtualenv
Virtualenv is probably what you want to use during development, you’ll probably want to use it there, too. You can read more about it at their documentation - http://virtualenv.readthedocs.org First, we need to install virtualenv to the system. This can be done with pip3 easily: pip3 install virtualenv
Once you have virtualenv installed, just fire up a shell and create your own environment. I usually create a project folder and a venv folder: $ virtualenv venv
Now, whenever you want to work on the project, you only have to activate the corresponding environment. On Unix based systems (OSX and Linux) this can be done with: $ source venv/bin/activate
And on Windows this is done with: $ venv\scripts\activate
Finally, you install coala and supported bears inside the activated virtualenv with: $ pip3 install coala-bears
1.3 Installing coala from source
In order to install coala from source, it is recommended to install git. See http://git-scm.com/ for further information and a downloadable installer or use your package manager on linux to get it.
Note: Again, here it is recommended to install coala inside a virtualenv. This can be done by creating a virtualenv and running the installation commands after the virtualenv has been activated.
After having git installed, you can download the source code of coala with the following command: git clone https://github.com/coala-analyzer/coala-bears/ cd coala-bears
You can now install coala with a simple: python3 setup.py install
For the above to work, you may also need to install setuptools which can be installed by running pip3 install setuptools
You will have coala installed into your python scripts directory. On an unixoid system it is probably already available on your command line globally. You may also install a development version of coala to test and make changes easily. To do this run: $ python3 setup.py develop
This essentially lets you install coala in a way that allows you to make changes to the code and see the changes take effect immediately.
2 Chapter 1. coala Installation coala Documentation, Release 0.5.2
1.3.1 Alternate installation
If you want to install coala to an alternate location you can e.g. call python3 setup.py install --prefix=/your/prefix/location. Other options are documented on https://docs.python.org/3.3/install/#alternate-installation.
Note: If you are using a proxy, follow these steps: • Set up your system-wide proxy. • Use sudo -E pip3 install coala (the -E flag takes the existing environment variables into the sudo environment). You could also set your pip.conf file to use a proxy, to know more read http://stackoverflow.com/questions/14149422/using-pip-behind-a-proxy for further clarification.
1.4 Dependencies
This section lists dependencies of coala that are not automatically installed. On Windows, you can get many with nuget (https://www.nuget.org/), on Mac Homebrew will help you installing dependencies (http://brew.sh/).
1.4.1 JS Dependencies
coala features a lot of bears that use linters written in JavaScript. In order for them to be usable, you need to install them via npm (http://nodejs.org/): npm install -g jshint alex remark dockerfile_lint csslint coffeelint
If a bear still doesn’t work for you, please make sure that you have a recent version of npm installed. Many linux distributions ship a very old one.
Note: If using coala from source you can just do npm install or npm install -g to use the package.json which is shipped with coala.
1.4.2 Binary Dependencies
Some bears need some dependencies available: • PHPLintBear: Install php • GNUIndentBear: Install indent (be sure to use GNU Indent, Mac ships a non-GNU version that lacks some functionality.) • CSharpLintBear: Install mono-mcs
1.4.3 Clang
coala features some bears that make use of Clang. In order for them to work, you need to install libclang: • Ubuntu: apt-get install libclang1
1.4. Dependencies 3 coala Documentation, Release 0.5.2
• Fedora: dnf install clang-libs (Use yum instead of dnf on Fedora 21 or lower.) • ArchLinux: pacman -Sy clang • Windows: nuget install ClangSharp • OSX: brew install llvm --with-clang If those do not help you, search for a package that contains libclang.so. On windows, you need to execute this command to add the libclang path to the PATH variable permanently (you need to be an administrator): setx PATH "%PATH%;%cd%\ClangSharp.XXX\content\x86" \M For x86 python or for x64 python: setx PATH "%PATH%;%cd%\ClangSharp.XXX\content\x64" \M Replace “XXX” with the ClangSharp version you received from nuget.
1.4.4 Generating Documentation coala documentation can be generated by fetching the documentation requirements. This can be achieved by pip3 install -r docs-requirements.txt
To generate the documentation coala uses sphinx. Documentation can be generated by running the following com- mand: python3 setup.py docs
You can then open docs\_build\html\index.html in your favourite browser. See Writing Documentation for more information.
4 Chapter 1. coala Installation CHAPTER 2
The .coafile Specification
This document gives a short introduction into the specification of a coala configuration file. It is meant to be rather factual, if you wish to learn by example, please take a look at the coala Tutorial.
2.1 Naming, Scope and Location
You can use up to three coafiles to configure your project. 1. A project-wide coafile. 2. A user-wide coafile. 3. A system-wide coafile.
2.1.1 Project-Wide coafile
It is a convention that the project-wide coafile is named .coafile and lies in the project root directory. If you follow this convention, simply executing coala from the project root will execute the configuration specified in that file. Settings given in the project-wide coafile override all settings given by other files and can only be overridden by settings given via the command line interface.
2.1.2 User-Wide and System-Wide coafile
You can place a .coarc file in your home directory to set certain settings user wide. Those settings will automatically be taken for all projects executed with that user. All settings specified here override only settings given by the system wide coafile which has the lowest priority. The default_coafile must lie in the coala installation directory and is valid for everyone using this coala installation
2.2 Setting Inheritance
Every coafile consists out of one or more sections. Section names are case insensitive. The default section is implicitly available and all settings which have no section specified belong to it. The default section is special because all settings residing in it are automatically inherited to all other sections specified in the same coafile. This is an example coafile:
5 coala Documentation, Release 0.5.2
enabled= True overridable=2
[section-1] overridable=3 other=4
[section-2] overridable=5 other=2
This coafile would be interpreted the very same as this one, written a bit more explicitly: [default] enabled= True overridable=2
[section-1] enabled= True overridable=3 other=4
[section-2] enabled= True overridable=5 other=2
2.2.1 Comments, Escaping and Multiline Values and Keys
Comments are simply done with a preceding #. If you want to use a # within a value, you can simply escape it: a_key = a\#value # And a comment at the end!
Any line not containing an unescaped = is simply appended to the value of the last key: a_key = a value # this is not part of the value that /= is very long!
Similarly, you can also set a value to multiple keys: key_1, key_2 = value is equivalent to key_1 = value and key_2 = value in separate lines. As the backslash is the escape character it is recommended to use forward slashes as path seperator even on windows (to keep relative paths platform independent), use double-backslashes if you really mean a backslash in all places.
6 Chapter 2. The .coafile Specification CHAPTER 3
Glob - Extended unix style pathname expansion
In coala, files and directories are specified by file name. To allow input of multiple files without requiring a large number of filenames, coala supports a number of wildcards. These are based on the unix-style glob syntax and they are not the same as regular expressions.
3.1 Syntax
The special characters used in shell-style wildcards are: PATTERN MEANING ‘[seq]’ Matches any character in seq. Cannot be empty. Any special character looses its special meaning in a set. ‘[!seq]’ Matches any character not in seq. Cannot be empty. Any special character looses its special meaning in a set. ‘(seq_a|seq_b)’ Matches either sequence_a or sequence_b as a whole. More than two or just one sequence can be given. ‘?’ Matches any single character. ‘*’ Matches everything but the directory separator ‘**’ Matches everything.
3.2 Examples
3.2.1 ‘[seq]’
Matches any character in seq. Cannot be empty. Any special character looses its special meaning in a set. Opening and closing brackets can be part of a set, although closing brackets have to be placed at the first position. >>> from coalib.parsing.Globbing import fnmatch >>> fnmatch("aaa","a[abc]a") True >>> fnmatch("aaa","a[bcd]a") False >>> fnmatch("aaa","a[a]]a") False >>> fnmatch("aa]a","a[a]]a") True >>> fnmatch("aaa","a[]abc]a") True
7 coala Documentation, Release 0.5.2
>>> fnmatch("aaa","a[[a]a") True >>> fnmatch("a[a","a[[a]a") True >>> fnmatch("a]a","a[]]a") True >>> fnmatch("aa","a[]a") False >>> fnmatch("a[]a","a[]a") True
3.2.2 ‘[!seq]’
Matches any character not in seq. Cannot be empty. Any special character looses its special meaning in a set. >>> fnmatch("aaa","a[!a]a") False >>> fnmatch("aaa","a[!b]a") True >>> fnmatch("aaa","a[b!b]a") False >>> fnmatch("a!a","a[b!b]a") True >>> fnmatch("a!a","a[!]a") False >>> fnmatch("aa","a[!]a") False >>> fnmatch("a[!]a","a[!]a") True
3.2.3 ‘(seq_a|seq_b)’
Matches either sequence_a or sequence_b as a whole. More than two or just one sequence can be given. Parentheses cannot be part of an alternative, unless they are escaped by brackets. Parentheses that have no match are ignored as well as ‘|’-separators that are not inside matching parentheses
>>> fnmatch("aXb","a(X|Y)b") True >>> fnmatch("aYb","a(X|Y)b") True >>> fnmatch("aZb","a(X|Y)b") False >>> fnmatch("aXb","(a(X|Y)b|c)") True >>> fnmatch("c","(a(X|Y)b|c)") True >>> fnmatch("a","a|b") False >>> fnmatch("a|b","a|b") True >>> fnmatch("(a|b","(a|b") True >>> fnmatch("(aa","(a(a|b)") True
8 Chapter 3. Glob - Extended unix style pathname expansion coala Documentation, Release 0.5.2
>>> fnmatch("a(a","(a(a|b)") False >>> fnmatch("a(a","(a[(]a|b)") True >>> fnmatch("aa","a()a") True >>> fnmatch("","(abc|)") True
3.2.4 ‘?’
Matches any single character. >>> fnmatch("abc","a?c") True >>> fnmatch("abbc","a?c") False >>> fnmatch("a/c","a?c") True >>> fnmatch("a\\c","a?c") True >>> fnmatch("a?c","a?c") True >>> fnmatch("ac","a?c") False
3.2.5 ‘*’
Matches everything but the directory separator
Note: The directory separator is platform specific. ‘/’ is never matched by ‘*’. ‘\’ is matched on Linux, but not on Windows.
>>> fnmatch("abc","a *c") True >>> fnmatch("abbc","a *c") True >>> fnmatch("a/c","a *c") False >>> fnmatch("a?c","a *c") True >>> fnmatch("ac","a *c") True
3.2.6 ‘**’
Matches everything.
>>> fnmatch("abc","a **c") True >>> fnmatch("abbc","a **c") True
3.2. Examples 9 coala Documentation, Release 0.5.2
>>> fnmatch("a/c","a **c") True >>> fnmatch("a?c","a **c") True >>> fnmatch("ac","a **c") True
10 Chapter 3. Glob - Extended unix style pathname expansion CHAPTER 4
Exit Codes
The following is a list of coalas exit codes and their meanings: • 0 - coala executed succesfully but yielded no results. • 1 - coala executed succesfully but yielded results. • 2 - Invalid arguments were passed to coala in the command line. • 3 - The file collector exits with this code if an invalid pattern is passed to it. • 4 - coala was executed with an unsupported version of python • 5 - coala executed successfully. Results were found but patches to the results were applied successfully • 13 - There is a conflict in the version of a dependency you have installed and the requirements of coala. • 130 - A KeyboardInterrupt (Ctrl+C) was pressed during the execution of coala. • 255 - Any other general errors.
11 coala Documentation, Release 0.5.2
12 Chapter 4. Exit Codes CHAPTER 5
External APIs
Use coala to make your application better.
5.1 DBus
The coala DBus API essentially creates a server which can have multiple clients connected to it. The clients commu- nicate to the coala server using DBus. To start the server, first install coala and then simple run coala-dbus. This spawns a bus with the name org.coala_analyzer.v1 as a SessionBus and can be verified and tested using a DBus debugger like DFeet. The bus has 1 object-path by default - /org/coala_analyzer/v1. This is the first point of contact with coala for any client. The object-path /org/coala_analyzer/v1 has the interface org.coala_analyzer.v1 which contains the two methods - CreateDocument and DisposeDocument. These are used to tell coala about the documents you wish to analyze.
5.1.1 CreateDocument
Args: the path of the document Returns: object-path for the document A document is defined by it’s path. The path should be a absolute path, not a relative one. This method returns an object-path which will be hence forth used to interact with that document.
5.1.2 DisposeDocument
Args: the path to the document Returns: none It disposes the object-path corresponding to the given path. Now, the object-path returned by the CreateDocument method also has the interface org.coala_analyzer.v1. This interface is used to handle which config file coala will use to analyze the document, and the function to get analysis results. It contains 4 functions:
13 coala Documentation, Release 0.5.2
5.1.3 GetConfigFile
Args: none Returns: the config file path
5.1.4 SetConfigFile
Args: the config file path Returns: the config path which is set after it executes.
5.1.5 FindConfigFile
Args: the config file path Returns: the config path which is set after it executes. It attempts to find the config file related to the file by searching in parent directories till it finds a .coafile.
5.1.6 Analyze
Args: none Returns: an array of DBus structures containing: • The name of the section • Boolean which is true if all bears in the section executed successfully • List of results where each result is a list which contains: (str)origin, (str)message, (str)file, (str)line_nr, (str)severity
14 Chapter 5. External APIs CHAPTER 6
Git Hooks
This document is a guide on how to add coala as a git hook. Using git hooks coala can be executed automatically, ensuring your code follows your quality requirements.
6.1 Pre Commit Hooks
The pre-commit hook can be used to run coala before every commit action. Hence, this does not allow any code not following the quality standars specified unless it’s done by force. To enable this, just create the file .git/hooks/pre-commit under your repository and add the lines: #!/bin/sh set-e coala
You can also specify arguments like -S autoapply=false which tells coala to not apply any patch by itself. Or you can run specific sections with coala
Note: If you allow coala to auto apply patches, it’s recommended to add *.orig to your .gitignore. coala creates these files while applying patches and they could be erroneously added to your commit.
This file needs to be executable. If it is not (or if you aren’t sure), you can make it executable by: $ chmod +x .git/hooks/pre-commit and you’re done! It will run every time before you commit, and prevent you from committing if the code has any errors.
15 coala Documentation, Release 0.5.2
16 Chapter 6. Git Hooks CHAPTER 7
coala Tutorial
Welcome to this little tutorial. It is meant to be a gentle introduction to the usage of coala.
7.1 Prerequisites
In order to complete this tutorial you will need coala installed. (Installation is actually not required but it’s more convenient and recommended.)
7.2 Get Some Code
In order to perform a static code analysis on your code you will need some code to check. If you do not have own code you want to check, you can retrieve our tutorial samples: git clone https://github.com/coala-analyzer/coala-tutorial.git
Please note that the commands given in this tutorial are intended for use with this sample code and may need minor adjustments.
7.3 Let’s Start!
There are two options how to let coala know what kind of analysis it should perform on which code.
7.3.1 Command Line Interface
In order to specify the files to analyze, you can use the --files argument of coala like demonstrated below. For all file paths, you can specify (recursive) globs. Because analysis routines can do many various things we named them Bears. Thus you can specify the kind of analysis with the --bears argument. Please type the following commands into the console: cd coala-tutorial coala --files=src/\*.c --bears=SpaceConsistencyBear --save
17 coala Documentation, Release 0.5.2
coala will now ask you for missing values that are needed to perform the analysis, which in this case is only the use_spaces setting. We recommend setting it to true. coala will now check the code and, in case you use the tutorial code, yield two results. In the case of the SpaceConsis- tencyBear you will see trailing whitespace errors on your console. Feel free to experiment a bit. You’ve successfully analysed some code! But don’t stop reading - you don’t have to enter all those values again!
7.3.2 Configuration Files
coala supports a very simple configuration file. If you’ve executed the instructions from the CLI section above, coala will already have such a file readily prepared for you. Go, take a look at it: cat.coafile
This should yield something like this: [Default] bears = SpaceConsistencyBear files = src/*.c use_spaces = yeah
If you now invoke coala it will parse this .coafile from your current directory. This makes it easy to specify once for your project what is checked with which bears and make it available to all contributors. Feel free to play around with this file. You can either edit it manually or add/edit settings via coala --save ... invocations. If you want coala to save settings every time, you can add save = True manually into your .coafile.
7.4 Sections
Thats all nice and well but we also have a Makefile for our project we want to check. So let us introduce another feature of our configuration syntax: sections. The line [Default] specifies that everything below will belong to the Default section. If nothing is specified, a setting will implicitly belong to this section. Let’s check the line lengths of our Makefile: coala -S Makefiles.bears=LineLengthBear Makefiles.files=Makefile --save
As you can see, the -S (or --settings) option allows to specify arbitrary settings. Settings can be directly stored into a section with the section.setting syntax. By default the LineLengthBear checks whether each line contains 80 chars or less in a line. To change this value, use the max_line_length inside the .coafile. coala will now yield any result you didn’t correct last time plus a new one for the Makefile. This time coala (or better, the LineLengthBear) doesn’t know how to fix the issue but still tries to provide as much helpful information as possible and provides you the option to directly open the file in an editor of your choice.
Note: If your editor is already open this may not work, because the other process will shortly communicate with the existent process and return immediately. coala handles this for some editors automatically, if your’s does not work yet - please file a bug so we can include it!
18 Chapter 7. coala Tutorial coala Documentation, Release 0.5.2
If you changed one file in multiple results, coala will merge the changes if this is possible. coala should have appended something like this to your .coafile: [Makefiles] bears= LineLengthBear files= Makefile
As you see, sections provide a way to have different configurations for possibly different languages in one file. They are executed sequentially.
7.5 Auto-applying results
Often you don’t want to look at trivial results like spacing issues. For that purpose coala includes a special setting called default_actions that allows you to set the action for a bear that shall be automatically applied on run. Let’s automatically fix python code. Take a look at our sample python code: $ cat src/add.py
""" This is a simple library that provide a function that can add numbers.
Cheers! """
def add(a,b): return a+b; import sys
That looks horrible, doesn’t it? Let’s fix it!
$ coala -S python.bears=PEP8Bear python.files=\*\*/\*.py \ python.default_actions=PEP8Bear:ApplyPatchAction --save # other output ... Executing section python... [INFO][11:03:37] Applied 'ApplyPatchAction' for 'PEP8Bear'. [INFO][11:03:37] Applied 'ApplyPatchAction' for 'PEP8Bear'. coala would now fix all spacing issues and without bothering you again. Currently following actions are available: • ApplyPatchAction: Applies a given patch (if existent). • ShowPatchAction: Just displays a given patch (if existent) without doing something. For debugging purposes: • PrintDebugMessageAction: Prints a debug message for the appearing result.
7.6 Setting Inheritance
All settings in the default section are implicitly inherited to all other sections (if they do not override their values). We can use that to save a few lines!
7.5. Auto-applying results 19 coala Documentation, Release 0.5.2
Lets add the following section to our .coafile: [TODOS] bears= KeywordBear
And execute coala with the -s argument which is the same as --save. I recommend setting case insensitive keywords to TODO, FIXME and case sensitive keywords empty. After the results we’ve already seen, we’ll see a new informational one which informs us that we have a TODO in our code. Did you note that we didn’t specify which files to check this time? This is because all settings, including files = src/*.c, from the Default section are already available in every other section implicitly. Thus the default section is a good point to set things like logging and output settings or specifying a default set of files to check.
7.7 Ignoring Issues
There are several ways to ignore certain issues, so you aren’t lost if any routines yield false positives.
7.7.1 Ignoring Files coala lets you ignore whole files through the ignore setting: files = **/*.h ignore = **/resources.h
This configuration would include all header (.h) files but leaves out resource headers.
7.7.2 Ignoring code Inside Files
Sometimes you need finer-graded ignores. Imagine you have a LineLengthBear that shall not run on some code segments, because you can’t wrap them: code="that's checked normally"
# Ignore LineLengthBear unwrappable_string="some string that is long and would exceed the limit"
You can also skip an area: # Start ignoring LineLengthBear unwrappable_string_2= unwrappable_string+"yeah it goes even further..." another_unwrappable_string= unwrappable_string+ unwrappable_string_2 # Stop ignoring
You can also conditionally combine ignore rules! Bear names will be split by comma and spaces, invalid bear names like and will be ignored. Also note that in the bear names delimited by commas and spaces, you may specify glob wildcards that match several bears:
# Start ignoring Line*, Py* unwrappable_string_2= unwrappable_string+"yeah it goes even further..." another_unwrappable_string= unwrappable_string+ unwrappable_string_2 # Stop ignoring
20 Chapter 7. coala Tutorial coala Documentation, Release 0.5.2
In the above example all bears matching the glob Line* and Py* will be ignored. You may also specify more complex globs here such as # Start ignoring (Line*|P[yx]*) which will ignore all bears start with Line, Py, and Px. # Ignore LineLengthBear and SpaceConsistencyBear variable = "Why the heck are spaces used instead of tabs..." + "so_long"
If you put an all instead of the bear names directly after the ignore/ignoring keyword, the results of all bears affecting those lines will be ignored.
7.8 Enabling/Disabling Sections
Now that we have sections we need some way to control, which sections are executed. coala provides two ways to do that:
7.8.1 Manual Enabling/Disabling
If you add the line TODOS.enabled=False to some arbitrary place to your .coafile or just enabled=False into the TODOS section, coala will not show the TODOs on every run. Especially for those bears yielding informational messages which you might want to see from time to time this is a good way to silence them.
7.8.2 Specifying Targets
If you provide positional arguments, like coala Makefiles, coala will execute exclusively those sections that are specified. This will not get stored in your .coafile and will take precedence over all enabled settings. You can specify several targets seperated by a space. What was that TODO again?
7.9 Show bears’ information
To get help on using a bear or to get a description of the bear, use the --show-bears argument: coala--bears=SpaceConsistencyBear--show-bears
This will display a large amount of information regarding the bears that have been specified (in the .coafile of in the CLI arguments). It shows: • A description of what the bear does • The sections which uses it • The settings it uses (optional and required)
7.10 Integrating coala into Your Project
It’s easy to add coala to your project in a way that does not force your developers even to install coala using git submodules. This also has the advantage that all your developers are using exactly the same version of coala. You can try it out in the coala-tutorial repository:
7.8. Enabling/Disabling Sections 21 coala Documentation, Release 0.5.2
git submodule add https://github.com/coala-analyzer/coala.git git commit -m 'Add coala submodule' git add .coafile git commit -m 'Add .coafile'
You can now use coala/coala as if it were the installed binary. Here’s the instructions for your developers: git submodule init git submodule update coala/coala
7.11 Continuing the Journey
If you want to know about more options, take a look at our help with coala -h. If you liked or disliked this tutorial, feel free to drop us a note at our bug tracker (github) or mailing list (https://groups.google.com/forum/#!forum/coala- devel). If you need more flexibility, know that coala is extensible in many ways due to its modular design: • If you want to write your own bears, take a look at sources lying in bears and coalib/bearlib. • If you want to add custom actions for results, take a look at the code in coalib/results/results_actions. • If you want to have some custom outputs (e.g. HTML pages, a GUI or voice interaction) take a look at modules lying in coalib/output. Happy coding!
22 Chapter 7. coala Tutorial CHAPTER 8
Guide to Write a Bear
Welcome. This document presents information on how to write a bear for coala. It assumes you know how to use coala. If not please read our main tutorial! The sample sources for this tutorial lie at our coala-tutorial repository, go clone it with: git clone https://github.com/coala-analyzer/coala-tutorial.git
All paths and commands given here are meant to be executed from the root directory of the coala-tutorial repository.
8.1 What is a bear?
A bear is meant to do some analysis on source code. The source code will be provided by coala so the bear doesn’t have to care where it comes from or where it goes. A bear can communicate with the user via two ways: • Via log messages • Via results Log messages will be logged according to the users settings and are usually used if something goes wrong. However you can use debug for providing development related debug information since it will not be shown to the user by default. If error/failure messages are used, the bear is expected not to continue analysis.
8.2 A Hello World Bear
Below is the code given for a simple bear that sends a debug message for each file: from coalib.bears.LocalBear import LocalBear class HelloWorldBear(LocalBear): def run(self, filename, file): self.debug("Hello World! Checking file", filename,".")
This bear is stored at ./bears/HelloWorldBear In order to let coala execute this bear you need to let coala know where to find it. We can do that with the -d (--bear-dirs) argument:
23 coala Documentation, Release 0.5.2
coala -f src/*.c -d bears -b HelloWorldBear -L DEBUG You should now see the debug message for our sample file. The Bear class also supports warn and err.
8.3 Communicating with the User
Now we can send messages through the queue, we can do the real work. Lets say: • We want some information from the user (e.g. the tab width if we rely on indentation) • We’ve got some useful information for the user and want to show it to him. This might be some issue with his code or just an information like the number of lines. So let’s extend our HelloWorldBear a bit, I’ve named the new bear with the creative name CommunicationBear: from coalib.bears.LocalBear import LocalBear from coalib.results.Result import Result class CommunicationBear(LocalBear):
def run(self, filename, file, user_input: str): """ Communicates with the user.
:param user_input: Arbitrary user input. """ self.debug("Got'{ui}' as user input of type {type}.".format( ui=user_input, type=type(user_input)))
return [Result.from_values(message="A hello world result.", origin=self, file=filename)]
Try executing it:
coala -f=src/\*.c -d=bears -b=CommunicationBear -L=DEBUG
Hey, we’ll get asked for the user_input! Wasn’t that easy? Go ahead, enter something and observe the output. So, what did coala do here? First, coala looked at the parameters of the run method and found that we need some value named user_input. Then it parsed our documentation comment and found a description for the parameter which was shown to us to help us choose the right value. After the needed values are provided, coala converts us the value into a string because we’ve provided the str annotation for this parameter. If no annotation is given or the value isn’t convertible into the desired data type, you will get a coalib.settings.Setting.Setting. Your docstring can also be used to tell the user what exactly your bear does. Try executing coala -d bears -b CommunicationBear --show-bears
24 Chapter 8. Guide to Write a Bear coala Documentation, Release 0.5.2
This will show the user a bunch of information related to the bear like: - A description of what the bear does - The sections which uses it - The settings it uses (optional and required)
8.3.1 What Data Types are Supported?
The Setting does support some very basic types: • String (str) • Float (float) • Int (int) • Boolean (bool, will accept values like true, yes, yeah, no, nope, false) • List of strings (list, values will be split by comma) • Dict of strings (dict, values will be split by comma and colon) If you need another type, you can write the conversion function yourself and use this function as the annotation. We’ve provided a few advanced conversions for you: • coalib.settings.Setting.path, converts to an absolute file path relative to the file/command where the setting was set • coalib.settings.Setting.path_list, converts to a list of absolute file paths relative to the file/command where the setting was set • coalib.settings.Setting.typed_list(typ), converts to a list and applies the given conversion (typ) to each element. • coalib.settings.Setting.typed_ordered_dict(key_type, value_type, default), converts to a dict while applying the key_type conversion to all keys, the value_type conversion to all values and uses the default value for all unset keys. Use typed_dict if the order is irrelevant for you.
8.4 Results
In the end we’ve got a result. If a file is provided, coala will show the file, if a line is provided, coala will also show a few lines before the affecting line. There are a few parameters to the Result constructor, so you can e.g. create a result that proposes a code change to the user. If the user likes it, coala will apply it automatically - you don’t need to care. Your function needs to return an iterable of Result objects: that means you can either return a list of Result objects or simply yield them and write the method as a generator.
Note: We are currently planning to simplify Bears for bear writers and us. In order to make your Bear future proof, we recommend writing your method in generator style. Don’t worry: in order to migrate your Bears to our new API, you will likely only need to change two lines of code. For more information about how bears will look in the future, please read up on https://github.com/coala- analyzer/coala/issues/725 or ask us on https://gitter.im/coala-analyzer/coala.
8.4. Results 25 coala Documentation, Release 0.5.2
26 Chapter 8. Guide to Write a Bear CHAPTER 9
Linter Bears
Welcome. This tutorial aims to show you how to use the Lint class in order to integrate linters in your bears.
9.1 Why is This Useful?
A lot of programming languages already have linters implemented, so if your project uses a language that does not already have a linter Bear you might need to implement it on your own. Don’t worry, it’s easy!
9.2 What do we Need?
First of all, we need the linter that we are going to use. In this tutorial we will build the HTMLTutorialBear so we need an html linter. This one will do. Since it is a python package we can go ahead and install it with $ pip install html-linter
9.3 Writing the Bear
Since we are going to use the Lint class we should go ahead and import it together with LocalBear (all bears that handle only one file inherit from LocalBear). Also we will go ahead and write the class head. It should inherit both LocalBear and Lint. from coalib.bearlib.abstractions.Lint import Lint from coalib.bears.LocalBear import LocalBear
class HTMLTutorialBear(LocalBear, Lint):
To make our bear use a linter we will have to overwrite some of the predefined values of the Lint class. Some of the most important are executable and output_regex. We use executable to specify the linter executable. In our case it would be executable='html_lint.py'
The output_regex is used to group parts of the output (such as lines, columns, severity and message) so it can be used by the Lint class to yield Results (more on communicating with the user Writing Bears). In order to figure out the output_regex we have to first see how the linter output looks. I will use this file as sample.html
27 coala Documentation, Release 0.5.2
Hello, world!
Now we can run $ html_lint.py sample.html 1:1: Info: Optional Tags: Omit optional tags (optional): You may remove the opening "html" tag. 2:3: Info: Optional Tags: Omit optional tags (optional): You may remove the opening "body" tag. 4:3: Info: Optional Tags: Omit optional tags (optional): You may remove the closing "body" tag. 5:1: Info: Optional Tags: Omit optional tags (optional): You may remove the closing "html" tag.
Our output_regex should look like this (line):(column): (severity): (message)
Or in python regex
(?P
Now that we found out our output_regex (we might want to test it just to be sure, https://regex101.com/#python is a great tool for this purpose). We can now compile and add our regex using the re python library like so (the regex was split into 2 lines to focus on readability) import re
from coalib.bearlib.abstractions.Lint import Lint from coalib.bears.LocalBear import LocalBear class HTMLTutorialBear(LocalBear, Lint): executable='html_lint.py' output_regex= re.compile( r'(?P
coala uses three types of severities • INFO • NORMAL • MAJOR which are defined in coalib.results.RESULT_SEVERITY. In order to use the severity group from the regex we will first have to map the output severities (as seen in the linter and as used in the regex above Info, Warning, Error) to the defined coala severities (above stated INFO, NORMAL, MAJOR). Luckily for us the Lint class provides us with the severity_map property. severity_map is just a dictionary of strings that should be mapped to the define coala severities. Let’s go ahead and import coalib.results.RESULT_SEVERITY and write our severity_map. Our code could look like this import re
from coalib.bearlib.abstractions.Lint import Lint from coalib.bears.LocalBear import LocalBear from coalib.results.RESULT_SEVERITY import RESULT_SEVERITY
28 Chapter 9. Linter Bears coala Documentation, Release 0.5.2
class HTMLTutorialBear(LocalBear, Lint): executable='html_lint.py' output_regex= re.compile( r'(?P
As with every other bear (see Writing Bears) we have to define our run method. def run(self, filename, file):
return self.lint(filename)
And that should be enough. The lint() method of the Lint class will do the rest for us. We can test our bear like this $ coala --bear-dirs=. --bears=HTMLTutorialBear --files=sample.html
Note: In order for the above command to work we should have 2 files in our current dir: HTMLTutorialBear.py and our sample.html. Naming is very important in coala. coala will look for bears by their filename and display them based on their classname.
9.4 Adding Settings to our Bear
If we run $ html_lint.py -h
We can see that there is a --disable option which lets us disable some checks. Let’s add that functionality to our bear. First of all we have to import the setting that we are going to use from coalib. Since --disable needs a comma separated list we can use a list to keep our options. For that we will import typed_list like so from coalib.settings.Setting import typed_list
typed_list(item_type) is a function that converts the given input (which the user will pass to the Bear as a setting) into a list of items and afterwards will apply a conversion to type item_type to each item in the list (you can also use basic types like int, bool, etc. see Writing Bears) Next, we have to add our setting as a parameter for the run() method of our bear. We will give the param a sugestive name like htmllint_ignore. def run(self, filename, file, htmllint_ignore: typed_list(str)=[]): ''' Checks the code with `html_lint.py` on each file separately.
9.4. Adding Settings to our Bear 29 coala Documentation, Release 0.5.2
:param htmllint_ignore: List of checkers to ignore. '''
Note: The documentation of the param is parsed by coala and it will be used as help to the user for that specific setting.
The last thing we need to do is join the strings in the html_ignore, append them to --disable= and add it as an argument. There are alot of ways of doing that. ignore=','.join(part.strip() for part in htmllint_ignore) self.arguments='--disable='+ ignore return self.lint(filename)
9.5 Right place for ‘{filename}’
Depending on where the executable (html_lint.py in this case) wants the file-name (eg. sample.html) to be present in the command which does the linting, we add ’{filename}’ to the arguments. When we run html_lint.py -h, we can see that the command signature is: html5_lint.py [--disable=DISABLE] FILENAME... So, we want ’{filename}’ at the end of the arguments. self.arguments='--disable='+ ignore self.arguments+=' {filename}' return self.lint(filename)
9.6 Finished Bear
Well done, you made it this far! Now you should have built a fully functional HTML Lint Bear. If you followed the code from this tutorial it should look something like this import re
from coalib.bearlib.abstractions.Lint import Lint from coalib.bears.LocalBear import LocalBear from coalib.settings.Setting import typed_list from coalib.results.RESULT_SEVERITY import RESULT_SEVERITY
class HTMLTutorialBear(LocalBear, Lint): executable='html_lint.py' output_regex= re.compile( r'(?P
def run(self,
30 Chapter 9. Linter Bears coala Documentation, Release 0.5.2
filename, file, htmllint_ignore: typed_list(str)=[]): ''' Checks the code with `html_lint.py` on each file separately.
:param htmllint_ignore: List of checkers to ignore. ''' ignore=','.join(part.strip() for part in htmllint_ignore) self.arguments='--disable='+ ignore self.arguments+=' {filename}' return self.lint(filename)
9.7 Running and Testing our Bear
By running $ coala --bear-dirs=. --bears=HTMLTutorialBear -B
We can see that our Bear setting is documented properly. To use coala with our Bear on sample.html we run $ coala --bear-dirs=. --bears=HTMLTutorialBear --files=sample.html
To use our htmllint_ignore setting we can do $ coala --bear-dirs=. --bears=HTMLTutorialBear \ > -S htmllint_ignore=optional_tag --files=sample.html
This will not output anything because all the messages had the optional_tag. You now know how to write a linter Bear and also how to use it in your project. Congratulations!
9.7. Running and Testing our Bear 31 coala Documentation, Release 0.5.2
32 Chapter 9. Linter Bears CHAPTER 10
Bears That Can Suggest And Make Corrections
Note: Go through the Linter Bears before reading this. Some executables (like indent or autopep8) can generate a corrected file from the original. We can use such executables so that coala, using these bears, can suggest and also make automatic corrections. Here’s an example bear. (GNUIndentBear) import platform from coalib.bearlib.abstractions.Lint import Lint from coalib.bearlib.spacing.SpacingHelper import SpacingHelper from coalib.bears.LocalBear import LocalBear class GNUIndentBear(Lint, LocalBear): executable="indent" if platform.system() !="Darwin" else "gindent" diff_message="Indentation can be improved." use_stdin= True gives_corrected= True
def run(self, filename, file, max_line_length: int=80, use_spaces: bool=True, tab_width: int=SpacingHelper.DEFAULT_TAB_WIDTH, indent_cli_options: str=''): """ This bear checks and corrects spacing and indentation via the well known Indent utility. It is designed to work with the C programming language but may work reasonably with syntactically similar languages.
:param max_line_length: Maximum number of characters for a line. :param use_spaces: True if spaces are to be used, else tabs. :param tab_width: Number of spaces per indent level. :param indent_cli_options: Any command line options the indent binary understands. They will be simply passed through. """ self.arguments="--no-tabs" if use_spaces else "--use-tabs" self.arguments+=(" --line-length {0} --indent-level {1}" "--tab-size {1} {2}".format(max_line_length,
33 coala Documentation, Release 0.5.2
tab_width, indent_cli_options)) return self.lint(filename, file)
In the example above, the important line is: gives_corrected= True
This tells the Lint class that this bear can suggest corrections. When we do this, internally a diff of the original file and the generated ‘corrected file’ along with some other not-important-for-this-tutorial magic is used to get the final output (which may be suggestions or auto-corrections). Let’s try this bear out. Create a new file called sample.cpp. Contents of sample.cpp are: #include
And, run the following command: coala --bear-dirs=. --bears=GNUIndentBear --files=sample.cpp -s
Make sure that both GNUIndentBear.py and sample.cpp are in your current folder. Also make sure that indent is installed (not the pip package, but the gnu one which can be installed using your system package manager). Now, we have a bear that is much more helpful than just a simple Linter Bear!
34 Chapter 10. Bears That Can Suggest And Make Corrections CHAPTER 11
Git tutorial
This tutorial will help you understand how git works and how to use git to submit your commit on Github.
Note: This tutorial is about using Git in bash/cmd, which we highly recommend, as it’s cleaner. Github is a totally different thing, it is the web interface or app.
11.1 How to install Git
First step is installing Git. Supposing you are on a Debian based distribution, this will do: $ sudo apt-get install git-all
11.2 Getting started with coala
First of all, you have to fork the repository you are going to contribute to. This will basically give you a clone of the repository to your own repository. You can do this by opening this to fork the coala website or this to fork the coala-bears website and then clicking ‘Fork’ in the upper right corner.
11.3 Grabbing coala on your local machine
Now you should clone the repository to your local machine so that you can have access to all the code and start fixing issues! To do this, you can use these to clone the coala / coala-bears repositories: $ git clone https://github.com/coala-analyzer/coala or $ git clone https://github.com/coala-analyzer/coala-bears
You should ideally clone the fork so that gets set to ‘origin’ automatically. Now you have all your code on your local machine!
35 coala Documentation, Release 0.5.2
11.4 Getting to work
First let’s talk about remotes. To communicate with the outside world, git uses what are called remotes. These are repositories other than the one on your local disk which you can push your changes into (so that other people can see them) or pull from (so that you can get others changes). Now you should add a remote to your local machine so that you can pull and push your commits. This can be simply done by using the command: $ git remote add myfork
Note: myfork is just a name we used for simplicity. You can name it however you want.
11.5 Creating a new branch
To start working on an issue, you first need to create a new branch where you will work. $ git checkout -b branchname
Note: checkout will switch to the newly created branch. -b will create a new branch if the branch doesn’t already exist.
11.6 Checking your work
After the issue is fixed and you have tested it (tests are very important! never submit a change that isn’t tested), you should check your progress. Type: $ git status
It will give you an idea about what files are currently modified.
Note: Tip: If there’s something you don’t find, you can always use: $ git grep "syntax" This will search through the whole repository and show you the files that contain the syntax.
See also: For more information about tests, check this link.
11.7 Adding the files and commiting
Now you can add your files/folders to the current commit: $ git add
Do this until you have added all the files needed for your commit. Then type:
36 Chapter 11. Git tutorial coala Documentation, Release 0.5.2
$ git commit
This will lead you to a text editor. Now you need to write your commit message. We are very strict about writing commit messages as they help us keep coala clean and stable. Commit messages usually consists of three main parts. They should have a newline between them. • The header The header should have the name of the file that you have made the change on, followed by ”:”, a space, and then a short title that explains the change made. Example: .gitignore: Add a new Constants variable • The body The body should have a short paragraph that briefly describes the change that was made, and the reason why this change was needed in imperative. Its maximum length is 50 characters. • The issue that is being fixed This part will usually have “Fixes
11.8 Pushing the commit
Now you will need to push the commit to the fork. All you have to do is: $ git push myfork
It will most likely ask for your login credentials from github. Type them in, and your commit will be pushed online.
11.9 Creating a Pull Request
Now you would like to get your commit into the actual master branch. Making your changes available to all future users of the project. For this, you will have to create a Pull Request. To do this, you will have to go on github, on your fork page. You should change to branch to the one you have worked on and submitted the commit on. Now you can create a Pull Request by clicking New Pull Request button in the pull request tab. Congratulations! You have just created your first Pull Request! You are awesome!
Note: If you see any error like 1 commit ahead of the master branch you need to sync your local fork with the remote repository before sending a pull request. More information regarding syncing can be found here.
11.10 Follow-up
Now after you have created the Pull Request, there are two possibilities:
11.8. Pushing the commit 37 coala Documentation, Release 0.5.2
• your PR will get accepted, and your commit will get merged into the master branch - sadly, this rarely happens on the first Pull Request • your PR will be rejected. There are 2 cases when a PR is rejected: – Test fails – Reviewer wants something changed (This also causes gitmate to fail) It’s highly unlikely that your PR will be accepted on the first attempt - but don’t worry that’s just how it works. It helps us keeping coala clean and stable. See also: Review Process. Now if you need to modify your code, you can simply edit it again, add it and commit it using $ git commit -a --amend
This will edit your last commit message. If your commit message was considered fine by our reviewers, you can simply send it again like this. If not, edit it and send it. Now you have successfully edited your last commit!
11.11 Keeping your fork in sync
As people work on coala new commits will be added. This will result in your local fork going out of sync with the remote repository. To sync your changes with the remote repository run the following commands in the desired branch: $ git fetch origin $ git rebase origin/master
This will fetch the commits from the remote repository and will merge it into the branch where you are currently working, and move all of the local commits that are ahead of the rebased branch to the top of the history on that branch.
Note: After following these instructions when you try to push to remote you may get fast-forwarding error. If that is the case, then you will have to force push since you are attempting to rewrite the git commit history. To do that append the --force argument in the push command: $ git push myfork --force Warning: Never force-push on the master branch, or any branch not owned by you.
11.12 Squashing your commits
It’s possible that you have more than one commits which you want them to be squashed into single commit. You can take your series of commits and squash them down into a single commit with the interactive rebasing tool. To squash your commits run the following command: $ git rebase -i master
Note: master is the SHA1 hash of the commit before which you want to squash all the commits and make sure that rebase is done onto master branch.
38 Chapter 11. Git tutorial coala Documentation, Release 0.5.2
An editor will be fired up with all the commits in your current branch (ignoring merge commits), which come after the given commit. Keep the first one as “pick” and on the second and subsequent commits with “squash”. After saving, another editor will be fired up with all the messages of commits which you want to squash. Clean up all the messages and add a new message which you want to be displayed for the single commit.
11.13 Useful Git commands
This section will briefly explain some other Git commands you will most likely use and will really make your work easier. $ git config
The git config command lets you configure your Git installation (or an individual repository) from the command line. This command can define everything from user info to preferences to the behavior of a repository. $ git log
The git log command displays committed snapshots. It lets you list the project history, filter it, and search for specific changes. While git status lets you inspect the working directory and the staging area, git log only operates on the committed history. $ git push --force myfork
While we normally use git push myfork to push your commit to your fork, after further editing and work on your commit, you will need to use the --force parameter to your push to automatically update your Pull Request. $ git reset --hard
Reset the staging area and the working directory to match the most recent commit. In addition to unstaging changes, the --hard flag tells Git to overwrite all changes in the working directory, too. Put another way: this obliterates all uncommitted changes, so make sure you really want to throw away your local developments before using it. $ git clean
The git clean command removes untracked files from your working directory. This is really more of a convenience command, since it’s trivial to see which files are untracked with git status and remove them manually. Like an ordinary rm command, git clean is not undoable, so make sure you really want to delete the untracked files before you run it. $ git checkout
The git checkout command is used to switch to another branch in the repository. Here
Rebasing is the process of moving a branch to a new base commit. From a content perspective, rebasing really is just moving a branch from one commit to another. But internally, Git accomplishes this by creating new commits and applying them to the specified base—it’s literally rewriting your project history. It’s very important to understand that, even though the branch looks the same, it’s composed of entirely new commits. $ git rebase -i
Running git rebase with the -i flag begins an interactive rebasing session. Instead of blindly moving all of the commits to the new base, interactive rebasing gives you the opportunity to alter individual commits in the process. This lets you clean up history by removing, splitting, and altering an existing series of commits. It’s like git commit --amend on steroids. Usage is $ git rebase -i
11.13. Useful Git commands 39 coala Documentation, Release 0.5.2 interactive rebasing session. This opens an editor where you can enter commands (described below) for each commit to be rebased. These commands determine how individual commits will be transferred to the new base. You can also reorder the commit listing to change the order of the commits themselves.
40 Chapter 11. Git tutorial CHAPTER 12
Welcome to the Newcomers guide!
This guide will help you to get involved and teach you how to make your first contribution to coala!
12.1 Meet the community!
To get started, the first step is to meet the community. We use gitter to communicate, and there the helpful community will guide you. Join us at coala gitter. The newcomers should ping us “Hello World” to let us know they are here because we care! Congratulations! You are now part of our community.
12.2 Start working
Let us know that you are interested in contributing on gitter and ask for an invitation to our org. This is your first step towards contributing. The invitation will be sent by mail and you will have to accept it to join. If you don’t find the invitation, accept it here. Now that you are part of our organization, you can start working on issues. If you are familiar with git, you can skip the next section and pick an issue.
12.3 Get help with git
We use github to manage our repository. If you’re not familiar with git, we strongly recommend following a tutorial, such as this one. If there’s anything unclear, or you are encountering problems, feel free to contact us on gitter, and we will help you!
12.4 Start working
Now is the time to pick an issue. Here is the link that will lead you to Newcomers issues. See also: For more information about what bears are, please check the following link: Writing bears The easy issues that will help you get started are labeled as “difficulty/newcomer” and are only there to give you a glimpse of how it is to work with us.
41 coala Documentation, Release 0.5.2
Now pick an issue which isn’t assigned, and if you want to fix it, then leave a comment that you would like to get assigned. This way we don’t have multiple people working on the same issue at the same time. Now you can start working on it. For more info on how to work correctly with git, try this.
Note: Before starting to write your first commit, check out this link: Writing good commits
12.5 Things to do before pushing
Now you need to make sure your change is actually working. For this, you will need to test it locally before pushing it to your fork, and checking it with concrete examples. So basically, run tests and run coala by simply typing $ coala into your bash. This will analyze your code and help you fix it. See also: Executing tests
12.6 Sending your changes
Now that you’ve fixed the issue, you’ve tested it and you think it is ready to be used, create a commit and push it to your fork, using: $ git push origin fix-branch
12.7 Creating a Pull Request
Now that your commit has been sent to your fork, it is time to do a Pull Request. It can be done by accessing your fork on github and clicking “New Pull Request”. Congratulations! You have now created your first Pull Request!
12.8 What to do after creating a PR
After creating your Pull Request, there’s two options: • your Pull Request gets accepted, and your commit will get merged into the master branch • your Pull Request doesn’t, and therefore you will need to to modify it as per the review comments It’s highly unlikely that your PR will be accepted on the first attempt - but don’t worry, that’s just how it works. It helps us keep coala clean and stable. See also: Review Process. Now if you need to modify your code, you can simply edit it again, add it and commit it using
42 Chapter 12. Welcome to the Newcomers guide! coala Documentation, Release 0.5.2
$ git commit -a --amend
This will edit your last commit message. If your commit message was considered fine by our reviewers, you can simply send it again like this. If not, edit it and send it. You have successfully edited your last commit!
Note: Don’t forget! After editing your commit, you will have to push it again. This can be done using:
$ git push --force origin
Congratulations! Your PR just got accepted! You’re awesome. Now try writing a bear, they are really rewarding!
12.8. What to do after creating a PR 43 coala Documentation, Release 0.5.2
44 Chapter 12. Welcome to the Newcomers guide! CHAPTER 13
Getting Involved
We are working hard to make coala reality. If you want to help us you can do the following things: • Join us on our mailing list. • coala developer list: https://groups.google.com/forum/#!forum/coala-devel – [email protected] • coala announcement list: https://groups.google.com/forum/#!forum/coala-announcements – [email protected] • Join us on our developer chatroom: https://gitter.im/coala-analyzer/coala • Run our tests. Just follow the instructions on the Testing page. Report back to us if anything goes wrong unexpectedly. • Give us feedback. If you think we’re doing something useless or useful with some specific things, please write us! We are interested in your needs and favors so you get the highest possible quality. • Drive bug discussions. Just state your opinion, everywhere! • Review code. Get a glance at what we’re doing and say something if you don’t understand something or think we’re doing something wrong. • Write documentation. If you need some additional information for documenting feel free to ask us! • Write code. Usually code we need is indicated through bug reports. Please get in contact with us so we can coordinate coding together. Please take a look at the other files in this directory for getting started with specific parts of coala. We appreciate any help. (Partially with words, partially with chocolate if you live near hamburg.) Modularity, clean good code as well as a high usability for both users and developers of analyse routines (called bears) stand in the foreground of the development. We will not speed up our development if it needs sacrificing any aspect of quality.
45 coala Documentation, Release 0.5.2
46 Chapter 13. Getting Involved CHAPTER 14
Codestyle for coala
coala follows the PEP8 codestyle with a maximum line length of 80 characters including newline. Invoke coala to let it correct your code automatically.
14.1 Additional Style Guidelines
14.1.1 Documentation Comments
A documentation comment consists of 2 parts - the description of what the function/class/module does followed by the parameters it takes in, the return value it gives out and the exceptions it can raise. Nothing should be written on the first and last line where the docstring begins and ends, and a newline should sep- arate the description and the rest. Each message in the documentation comment must end with a full-stop. Also the description of all arguments and the return value should begin at the same column. Example: def area(length, breadth): """ Finds the area of a rectangle of the given length and breadth.
:param length: The length of the rectangle. :param breadth: The breadth of the rectangle. :return: The area of the rectangle. :raises ValueError: Raises ValueError if the arguments are not of type float or int. """
If the description for a param or other keywords exceeds 1 line, continue it in the next. Make sure that the second line is aligned Below the first line. Example : :param something: A very long line describing the variable something in great detail. :return: This message also started in the same column and it starts again at the same column as the rest of the messages.
47 coala Documentation, Release 0.5.2
14.1.2 Type Checking
If you want to assure that parameters have a certain type, you can use the enforce_signature decorator and simply annotate your function with the allowed types: @enforce_signature def concatenate_strings(a: str, b: str, c: (str, None)=None): if c is None: c="" return a+b+c
This will raise a TypeError if a, b or c are no strings and c is not None.
48 Chapter 14. Codestyle for coala CHAPTER 15
Introduction
At coala we are looking heavily at the maintainability of the code. Code is more often read than written! It is obvious that we need good code. In order to do that we are verifying that every change to our code (i.e. the commits) is making it better.
15.1 What Makes a Good Commit
A good commit is atomic. It describes but only one logical change and not more. Why do we do that? Because we find more bugs if we do! Also it features a good commit message.
15.2 How to Write Good Commit Messages
A commit message consists of 3 parts - The shortlog (short description), the long description and the issue reference. There should have an empty line between each section. This is the shortlog - one line only
This is the long description which can extend to multiple lines of text.
And can have multiple paragraphs which explain things in more detail too.
Next is the issue reference
15.2.1 Shortlog
Example: setup: Install .coafile via package_data
• Maximum of 50 characters. • Should describe the change - the action being done in the commit. • Should have a tag and and a short description separated by a colon (:)
49 coala Documentation, Release 0.5.2
– Tag
* The file or class or package being modified. * Not mandatory. – Short Description
* Starts with a capital letter. * Written in imperative present tense (i.e. Add something, not Adding something or Added something).
* No trailing period.
15.2.2 Long Description
Example: When installing the .coafile to distutils.sysconfig.get_python_lib, we ignore that this is not the installation directory in every case. Thus it is easier, more reliable and platform independent to let distutils install it by itself.
• Maximum of 72 chars excluding newline for each line. • Not mandatory - but helps explain what you’re doing. • Should describe the reasoning for your changes. This is especially important for complex changes that are not self explanatory. This is also the right place to write about related bugs.
15.2.3 Issue reference
Example: Fixes https://github.com/coala-analyzer/coala/issues/269
• Should use the Fixes keyword. • Should use full URL to the issue. • There should be a single space between the Fixes and the URL.
Note: • The issue reference will automatically add the link of the commit in the issue. • It will also automatically close the issue when the commit is accepted into coala.
See also: https://wiki.gnome.org/Git/CommitMessages
15.2.4 Example
50 Chapter 15. Introduction coala Documentation, Release 0.5.2
setup: Install .coafile via package_data
When installing the .coafile to distutils.sysconfig.get_python_lib, we ignore that this is not the installation directory in every case. Thus it is easier, more reliable and platform independent to let distutils install it by itself.
Fixes https://github.com/coala-analyzer/coala/issues/269
15.3 Why Do We Need Good Commits?
• An atomic commit is way easier to review. The reviewer thus will be able to review faster and find more bugs due to the lower complexity of the change. • Atomic commits are like good objects in object oriented programming - you can split up a bigger thing into many small objects. Reducing complexity is the key to developing good software and finding its bug before they occur. • Good commit messages make it easy to check at a glance what happened in a time range. • It is way easier to revert single changes without side effects. Reverting multiple commits at a time is easy, reverting a part of a commit is not. • git blame will be much more effective. It is the best documentation you can get. The older your code is, the more documentation it has. The better the commit messages are, the better is your hidden documentation. Your commit messages document the reason for every single change you did to any line. • git bisect will be much more effective. If you bisect through atomic commits to find the commit which caused a bug, you should be able to identify the real cause of the bug fastly. Good commit messages and atomicity of commits are key to that ability.
15.3. Why Do We Need Good Commits? 51 coala Documentation, Release 0.5.2
52 Chapter 15. Introduction CHAPTER 16
Testing
You can help us testing coala in several ways.
16.1 Executing our Tests coala has a big test suite. It is meant to work on every platform on every PC. If you just execute our tests you are doing us a favor. To run tests, you first need to install some dependencies. This can be done by executing: $ pip3 install -r test-requirements.txt
You can then execute our tests with $ py.test and report any errors you get! To run our tests, you can also use python3 setup.py test
Note: If you need to customize test running, you can get more options about allowing skipped tests, getting code coverage displayed or omitting/selecting tests using py.test directly. $ py.test --help
Note: You will not get a test coverage of 100% - the coverage on the website is merged for several python versions.
16.2 Using test coverage
To get coverage information, you can run: $ py.test --cov
You can view the coverage report as html by running: $ py.test --cov --cov-report html
The html report will be saved .htmlreport inside the coala repository.
53 coala Documentation, Release 0.5.2
54 Chapter 16. Testing CHAPTER 17
Reviewing
This document is a guide to coalas review process. It will be extended over time.
17.1 Review Process
The review process for coala is as follows: 1. Anyone can submit commits for review. This usually happens on WIP branches, submitting goes via GitHub Pull Requests. 2. A reviewer reviews every commit by its own and validates that every commit is a good change and does not destroy anything. 3. If a commit does not fulfill the expectations of the reviewer, go to step one. 4. If the commits are not linearly mergeable into master, rebase and go to step one. 5. All commits are acknowledged and fit linearly onto master. All continuous integration services (as described below) pass. Anyone with collaborator permission may leave the @rultor merge command to get the PR merged automatically.
17.2 Continous Integration
It is only allowed to merge a pull request into master if all of the following apply: • The build/tests pass on all services. (circleci, appveyor) • Scrutinizer shows passed. (That is: no new issues, no new classes with rating D or worse, project quality metric may only get better.) • All statements and branches are covered by your tests. (codecov.io) The coverage values may go down by a commit, however this is to be avoided. Tests must work for every commit. Continuous integration is always done for the last commit on a pull request.
17.3 Reviewing Commits
• Generated code is not intended to be reviewed. Instead rather try to verify that the generation was done right. The commit message should expose that.
55 coala Documentation, Release 0.5.2
• Every commit is reviewed independently from the other commits. • Tests should pass for each commit. If you suspect that tests might not pass and a commit is not checked by continuous integration, try running the tests locally. • Check the surroundings. In many cases people forget to remove the import when removing the use of something or similar things. It is usually good to take a look at the whole file to see if it’s still consistent. • Check the commit message. • Take a look at continuous integration results in the end even if they pass: • Coverage shall not fall. • Scrutinizer oftentimes yields helpful results.
56 Chapter 17. Reviewing CHAPTER 18
Introduction
Tests are an essential element to check if your written components in coala really do work like they should. Even when you think “I really looked over my code, no need for tests” you are wrong! Bugs introduced when not writing tests are often the most horrible ones, they have the characteristic to be undiscoverable (or only discoverable after dozens of hours of searching). Try to test as much as possible! The more tests you write the more you can be sure you did everything correct. Especially if someone else modifies your component, he can be sure with your tests that he doesn’t introduce a bug.
18.1 Actually Writing a Test
So how do you implement a test in coala? First up, tests are placed into the bears/tests (if you want to write a test for a bear) or tests (if you test a component written for the coalib) directory. They are also written in python (version 3) and get automatically executed by running: $ py.test
There’s only one constraint: The name of the test file has to end with Test.py (for example MyCustomTest.py, but not MyCustomTestSuite.py).
Note: Often you don’t want to run all available tests. To run your specific one, type (in the coala root folder): $ py.test -k
You can even give partial names or queries like “not MyCustomTest” to not run a specific test. More information can be got with py.test -h
Coming to the test file structure. Every test script starts with your system imports, i.e.: # Imports the python 're' package for regex processing. import re import unittest # ...
As said before, in the next line your own imports follow. So just import what you need from coala: import coalib.your_component.component1 import coalib.your_component.component2 # ...
57 coala Documentation, Release 0.5.2
Note: You can use system imports here also, but the coala codestyle suggests to place them above the three setup lines, like before.
Then the actual test suite class follows, that contains the tests. Each test suite is made up of test cases, where the test suite checks the overall functionality of your component by invoking each test case. The basic declaration for a test suite class is as follows: class YourComponentTest(unittest.TestCase): # Your test cases. pass
You should derive your test suite from unittest.TestCase to have access to the setUp() and tearDown() functions (covered in section below: ‘‘setUp()‘‘ and ‘‘tearDown()‘‘) and also to the assertion functions. Now to the test cases: To implement a test case, just declare a class member function without parameters, starting with test_. Easy, isn’t it? class YourComponentTest(unittest.TestCase): # Tests somethin'. def test_case1(self): pass
# Doesn't test, this is just a member function, since the function name # does not start with 'test_'. def not_testing(self): pass
But how do you actually test if your component is correct? For that purpose you have asserts. Asserts check whether a condition is fulfilled and pass the result to the overall test-suite-invoking-instance, that manages all tests in coala. The result is processed and you get a message if something went wrong in your test. Available assert functions are listed in the section Assertions below. So an example test that succeeds would be: # The sys import and setup is not needed here because this example doesn't # use coala components. import unittest
class YourComponentTest(unittest.TestCase): # Tests somethin'. def test_case1(self): # Does '1' equal '1'? Interestingly it does... mysterious... self.assertEqual(1,1) # Hm yeah, True is True. self.assertTrue(True)
Note: Tests in coala are evaluated against their coverage, means how many statements will be executed from your component when invoking your test cases. A branch coverage of 100% is needed for any commit in order to be pushed to master - please ask us on gitter if you need help raising your coverage! The branch coverage can be measured locally with the py.test --cov command. See also: Module Executing Tests Documentation of running Tests with coverage
58 Chapter 18. Introduction coala Documentation, Release 0.5.2
As our coverage is measured across builds against several python versions (we need version specific branches here and there) you will not get the full coverage locally! Simply make a pull request to get the coverage measured automatically. If some code is untestable, you need to mark your component code with # pragma: no cover. Important: Provide a reason why your code is untestable. Code coverage is measured using python 3.3 and 3.4 on linux. # Reason why this function is untestable. def untestable_func(): # pragma: no cover # Untestable code. pass
18.2 setUp() and tearDown()
Often you reuse components or need to make an inital setup for your tests. For that purpose the function setUp() exists. Just declare it inside your test suite and it is invoked automatically once at test suite startup: class YourComponentTest(unittest.TestCase): def setUp(self): # Your initialization of constants, operating system API calls etc. pass
The opposite from this is the tearDown() function. It gets invoked when the test suite finished running all test cases. Declare it like setUp() before: class YourComponentTest(unittest.TestCase): def tearDown(self): # Deinitialization, release calls etc. pass
18.3 Assertions
Here follows a list of all available assertion functions supported when inheriting from unittest.TestCase: • assertEqual(a, b) Checks whether expression a equals expression b. • assertNotEqual(a, b) Checks whether expression a not equals expression b. • assertTrue(a) Checks whether expression a is True. • assertFalse(a) Checks whether expression a is False. • assertIs(a, b) Checks whether expression a is b. • assertIsNot(a, b) Checks whether expression a is not b.
18.2. setUp() and tearDown() 59 coala Documentation, Release 0.5.2
• assertIsNone(a) Checks whether expression a is None. • assertIsNotNone(a) Checks whether expression a is not None. • assertIn(a, list) Checks whether expression a is an element inside list. • assertNotIn(a, list) Checks whether expression a is not an element inside list. • assertIsInstance(a, type) Checks whether expression a is of type type. • assertNotIsInstance(a, type) Checks whether expression a is not of type type. • assertRaises(error, function, *args, **kwargs) Checks whether function throws the specific error. When calling this assert it invokes the function with the specified *args and **kwargs. If you want more information about the python unittest-module, refer to the official documentation and for asserts the subsection [assert-methods] (https://docs.python.org/3/library/unittest.html#assert-methods).
18.4 Kickstart
This section contains a concluding and simple example that you can use as a kickstart for test-writing. Put the code under the desired folder inside tests or bears/tests, modify it to let it test your stuff and run the test from the coala root folder py.test. # Import here your needed system components. import sys import unittest
sys.path.insert(0,".") # Import here your needed coala components.
# Your test unit. The name of this class is displayed in the test # evaluation. class YourTest(unittest.TestCase): def setUp(self): # Here you can set up your stuff. For example constant values, # initializations etc. pass
def tearDown(self): # Here you clean up your stuff initialized in setUp(). For example # deleting arrays, call operating system API etc. pass
def test_case1(self):
60 Chapter 18. Introduction coala Documentation, Release 0.5.2
# A test method. Put your test code here. pass
18.4. Kickstart 61 coala Documentation, Release 0.5.2
62 Chapter 18. Introduction CHAPTER 19
Writing Documentation
This document gives a short introduction on how to write documentation for the coala project. Documentation is written in reStructuredText and rendered by readthedocs.org to our lovely users. You can view the current documentation on http://coala.rtfd.org. After getting the coala source code (see Installation Instructions), you can start hacking on existent documentation files. They reside in the docs directory and are written in reStructuredText. If you want to add new pages, you need to alter the index.rst file in the coala docs directory. Please read http://www.sphinx-doc.org/en/stable/markup/toctree.html#toctree-directive for an explanation of the syntax. You can test the documentation locally through simply running make html in the coala docs directory. This gen- erates docs\_build\html\index.html that you can view on your browser. (Use pip3 install sphinx if you do not have sphinx yet.)
63 coala Documentation, Release 0.5.2
64 Chapter 19. Writing Documentation CHAPTER 20
Coverage Installation Hints for OSX Users:
20.1 1. Make sure you have installed Xcode and Homebrew.
20.2 2. Install Python3. brew search python # This should display python3 brew install python3 python3 --version # To check the installed version
20.3 3. Create Virtual environments with pyvenv
# Create Virtual Env named myenv pyvenv myenv
# This will create a folder named myenv in the # current directory. To activate this environment just type source myenv/bin/activate
# You can start Python3 by typing: python
20.4 4. Virtualenvwrapper with Python 3:
# Installation pip3 install virtualenv pip3 install virtualenvwrapper
# Folder to contain Virtual Environments mkdir ~/.virtualenvs
# Add the following in ~/.bash_profile export WORKON_HOME=~/.virtualenvs source /usr/local/bin/virtualenvwrapper.sh
# Activate Changes source ~/.bash_profile
65 coala Documentation, Release 0.5.2
# Get Python3 path (python3_pth) where python3
# Create a new virtual environment with Python3 mkvirtualenv --python=python3_path myenv
20.5 Finally!
# Install python-coverage3 by easy_install coverage
66 Chapter 20. Coverage Installation Hints for OSX Users: CHAPTER 21
A Hitchhiker’s Guide to Git(1): Genesis
21.1 Introduction
21.1.1 What is This?
This post tries to provide a gentle introduction to git. While it is aimed at newcomers it is also meant to give a rather good overview and understanding of what one can do with git and thus is extensive. It follows the premise: If you know how a thing works, you can make it do what you want it to. Please don’t be afraid as I’m trying to use light language and many examples so you can read fast through it and understand anyway (if I succeed). I’m also trying to highlight important things at least for long texts to ease reading a bit more. However, at some points this tutorial may require you to think for yourselves a bit - it’s a feature, not a bug.
21.1.2 For Whom is This?
This tutorial is meant for everyone willing to learn git - it does not matter if you are a developer who never really got the hang of it or a student wanting to learn. Even if you are doing non coding tasks like design or documentation git can be a gift from heaven. This tutorial is for everyone - don’t be scared by its length and believe me, it pays off! The only requirement is that you have git installed, know cd, ls and mkdir and have something to commit - and who doesn’t have any digital data!?
21.1.3 What’s in There?
This tutorial is the first out of three tutorials which are meant to free your mind from a traditional view on filesys- tems.
Genesis
This tutorial, Genesis (i.e. “Creation” or “Beginning”), will cover some very basic things: • Configuring git so you can use it how you want. (Basic, aliases) • Creating your git repository (play god once!) • Creating your first git commits. • Learning what the repository is and where commits get stored.
67 coala Documentation, Release 0.5.2
• Browsing through history. • Ignoring files.
Exodus
Exodus (i.e. “going out”) will cover: • Store temporary changes without committing. • Navigating commits in git. • Sharing commits to a remote place. • Locally (huh, that’s sharing?) • Via email • To a server • To a client • Working with others (i.e. non-linear). • Join things. • Linearize things. • Writing good commits. • Editing commits. (Actually not editing but it feels like that.)
Apocalypse
Apocalypse (i.e. “uncovering”) will try to uncover some more advanced features of git, finally freeing your mind from your non-versioned filesystem: • Finding more information about code. • Finding causes of bugs in git. • Reverting commits. • Reviewing commits. • Travelling though time and changing history (you want me to believe you’ve never wanted to do that?) • Getting back lost things. • Let git do things automatically.
21.1.4 Some Warnings
A short warning: If you ever really got the hang of git you will not be able to use something else without symptoms of frustration and disappointment - you’ll end up writing every document versioned as an excuse to use git. A warning for windows users: you may need to use equivalent commands to some basic UNIX utilities or just install them with git. (Installer provides an option for that.) In general it’s a bit like travelling with Vogons - avoid when possible. A warning for GUI users: Don’t use your GUI. Be it the GitHub App or SourceTree or something else - they usually try to make things more abstract for us, thus they hinder us from understanding git and we can then not make git do what we want. Being able to communicate directly with git is a great thing and really bumps productivity!
68 Chapter 21. A Hitchhiker’s Guide to Git(1): Genesis coala Documentation, Release 0.5.2
I wrote this tutorial to the best of my knowledge and experience, if you spot an error or find something important is missing, be sure to drop me a message!
21.1.5 Preparation...
So go now, grab a cup of coffee (or any other drink), a towel, take your best keyboard and open a terminal beneath this window!
21.2 What’s Git for Anyway?
Before we really get started it is important to know what git roughly does: git is a program that allows you to manage files. To be more specific git allows you to define changes on files. In the end your repository is just a bunch of changes that may be related to each other.
21.3 Setting Up Git
Before we can continue we’ll have to set up a few tiny things for git. For this we will use the git config --global command which simply stores a key value pair into your user-global git configuration file (usually stored at ~/.gitconfig).
21.3.1 WHOAMI
Let’s tell git who we are! This is pretty straightforward: $ git config --global user.name "Ford Prefect" $ git config --global user.email [email protected]
This makes git store values for “name” and “email” within the “user” section of the gitconfig.
21.3.2 Editor
For some operations git will give you an editor so you can enter needed data. This editor is vim by default. Some people think vim is great (vim is great!), some do not. If you belong to the latter group or don’t know what vim is and how to operate it, let’s change the editor: $ # Take an editor of your choice instead of nano $ git config --global core.editor nano
Please make sure that the command you give to git always starts as an own process and ends only when you finished editing the file. (Some editors might detect running processes, pass the filename to them and exit immediately. Use -s argument for gedit, --wait argument for sublime.) Please don’t use notepad on windows, this program is a perfect example of a text editor which is too dumb to show text unless the text is written by itself.
21.4 Create a Repository
So, lets get started - with nothing. Let’s make an empty directory. You can do that from your usual terminal:
21.2. What’s Git for Anyway? 69 coala Documentation, Release 0.5.2
$ mkdir git-tutorial $ cd git-tutorial $ ls -a ./ ../
So, lets do the first git command here: $ git init Initialized empty Git repository in /home/lasse/prog/git-tutorial/.git/ $ ls -a ./ ../ .git/
So now we’ve got the .git folder. Since we just created a repository with git init, so we can deduce, that this .git directory must in fact be the repository!
21.5 Creating a God Commit
So, let’s create some content we can manage with git: $ echo 'Hello World!' >> README $ cat README Hello World!
Since we know, that the .git directory is our repository, we also know that we did not add this file to our repository yet. So how do we do that? As I’ve hinted before, our git repository does not contain files but only changes - so how do we make a change out of our file? The answer lies in (1) git add and (2) git commit which allows us to (1) specify what files/file changes we want to add to the change and (2) that we want to pack those file changes into a so-called commit. Git also offers a helper command so we can see what will be added to our commit: git status. Let’s try it out: $ git status On branch master
Initial commit
Untracked files: (use "git add
README
nothing added to commit but untracked files present (use "git add" to track) $ git add README $ git status On branch master
Initial commit
Changes to be committed: (use "git rm --cached
new file: README
So obviously with git add we can stage files. What does that mean?
70 Chapter 21. A Hitchhiker’s Guide to Git(1): Genesis coala Documentation, Release 0.5.2
As we know, when we’re working in our directory any actions on files won’t affect our repository. So in order to add a file to the repository, we’ll have to put it into a commit. In order to do that, we need to specify, what files/changes should go into our commit, i.e. stage them. When we did git add README, we staged the file README, thus every change we did until now to it will be included in our next commit. (You can also partially stage files so if you edit README now the change won’t be committed.) Now we’ll do something very special in git - creating the first commit! (We’ll pass the -v argument to get a bit more info from git on what we’re doing.) $ git commit -v
You should now get your editor with contents similar to this: # Please enter the commit message for your changes. Lines starting # with '#' will be ignored, and an empty message aborts the commit. # On branch master # # Initial commit # # Changes to be committed: # new file: README #ref: refs/heads/master
# ------>8 ------# Do not touch the line above. # Everything below will be removed. diff --git a/README b/README new file mode 100644 index 0000000..c57eff5 --- /dev/null +++ b/README @@ -0,0 +1 @@ +Hello World!
Since we’re about to create a change, git asks us for a description.
Note: Git actually allows creating commits without a description with a special argument. This is not recommended for productive collaborative work!)
Since we passed the -v parameter, git also shows us below what will be included in our change. We’ll look at this later. Commit messages are usually written in imperative present tense and should follow certain guidelines. We’ll come to this later. So, let’s enter: Add README as our commit message, save and exit the editor. Now, let’s take a look at what we’ve created, git show is the command that shows us the most recent commit: $ git show commit ec6c903a0a18960cd73df18897e56738c4c6bb51 Author: Lasse Schuirmann
Add README
diff --git a/README b/README new file mode 100644 index 0000000..980a0d5
21.5. Creating a God Commit 71 coala Documentation, Release 0.5.2
--- /dev/null +++ b/README @@ -0,0 +1 @@ +Hello World!
So what do we see here: • It seems that commits have an ID, in this case ec6c903a0a18960cd73df18897e56738c4c6bb51. • Commits also have an author and a creation date. • Of course they hold the message we wrote and changes to some files. What we see below the diff ... line is obviously the change. Let’s take a look at it: since git can only describe changes, it takes /dev/null (which is a bit special, kind of an empty file, not important here), renames it to README and fills it with our contents. So, this commit is pretty godish: It exists purely on it’s own, has no relations to any other commit (yet, it’s based on an empty repository, right?) and creates a file out of nothing (/dev/null is somehow all and nothing, kind of a unix black hole).
21.6 Inspecting What Happened
So, let’s look in our repository! $ ls -la .git total 52 drwxrwxr-x. 8 lasse lasse 4096 Feb 27 16:05 ./ drwxrwxr-x. 3 lasse lasse 4096 Feb 27 14:11 ../ drwxrwxr-x. 2 lasse lasse 4096 Feb 27 14:11 branches/ -rw-rw-r--. 1 lasse lasse 486 Feb 27 14:12 COMMIT_EDITMSG -rwxrw-r--. 1 lasse lasse 92 Feb 27 14:11 config* -rw-rw-r--. 1 lasse lasse 73 Feb 27 14:11 description -rw-rw-r--. 1 lasse lasse 23 Feb 27 14:11 HEAD drwxrwxr-x. 2 lasse lasse 4096 Feb 27 14:11 hooks/ -rw-rw-r--. 1 lasse lasse 104 Feb 27 14:11 index drwxrwxr-x. 2 lasse lasse 4096 Feb 27 14:11 info/ drwxrwxr-x. 3 lasse lasse 4096 Feb 27 14:12 logs/ drwxrwxr-x. 7 lasse lasse 4096 Feb 27 14:12 objects/ drwxrwxr-x. 4 lasse lasse 4096 Feb 27 14:11 refs/ $
Now let’s look into it further to get to know what it is a bit more. I will try to cover only important parts here, if you’re interested even deeper, you can try DuckDuckGo or take a look at this: http://git-scm.com/docs/gitrepository-layout
21.6.1 The config file
The config file is a similar file to the one where our settings in the beginning got stored. (User and editor configuration, remember?) You can use it to store settings per repository.
21.6.2 The objects directory
The objects directory is an important one: It contains our commits. One could do a full tutorial on those things but that’s not covered here. If you want that, check out: http://git- scm.com/book/en/v2/Git-Internals-Git-Objects
72 Chapter 21. A Hitchhiker’s Guide to Git(1): Genesis coala Documentation, Release 0.5.2
We just saw the ID of the commit we made: ec6c903a0a18960cd73df18897e56738c4c6bb51 Now let’s see if we find it in the objects directory: $ ls .git/objects 98/ b4/ ec/ info/ pack/ $ ls .git/objects/ec 6c903a0a18960cd73df18897e56738c4c6bb51
So, when we create a commit, the contents (including metadata) are hashed and git stores it finely into the objects directory. That isn’t so complicated at all, is it?
Task: Objects git show accepts a commit ID as an argument. So you could e.g. do git show ec6c903a0a18960cd73df18897e56738c4c6bb51 instead of git show if this hash is the current commit. Investigate what the other two objects are, which are stored in the objects directory. (Ignore the info and pack subdi- rectory.) Do git show again and take a look at the line beginning with “index”. I’m sure you can make sense out of it!
21.6.3 The HEAD File
The HEAD file is here so git knows what the current commit is, i.e. with which objects it has to compare the files in the file system to e.g. generate a diff. Let’s look into it: $ cat .git/HEAD ref: refs/heads/master
So it actually only references to something else. So let’s take a look into refs/heads/master - what ever this is: $ cat .git/refs/heads/master ec6c903a0a18960cd73df18897e56738c4c6bb51
So this HEAD file refers to this master file which refers to our current commit. We’ll see how that makes sense later.
21.7 Creating a Child Commit
Now, let’s go on and create another commit. Let’s add something to our README. You can do that by yourself, I’m sure! Let’s see what we’ve done: $ git diff diff --git a/README b/README index 980a0d5..c9b319e 100644 --- a/README +++ b/README @@ -1 +1,2 @@ Hello World! +Don't panic!
21.7. Creating a Child Commit 73 coala Documentation, Release 0.5.2
Let’s commit it. However, since we’re a bit lazy we don’t want to add the README manually again; the commit command has an argument that allows you to auto-stage all changes to all files that are in our repository. (So if you added another file which is not in the repository yet it won’t be staged!) git commit -a -v
Well, you know the game. Can you come up with a good message on your own? $ git show commit 7b4977cdfb3f304feffa6fc22de1007dd2bebf26 Author: Lasse Schuirmann
README: Add usage instructions
diff --git a/README b/README index 980a0d5..c9b319e 100644 --- a/README +++ b/README @@ -1 +1,2 @@ Hello World! +Don't panic!
So this commit obviously represents the change from a file named README which contents are stored in object 980a0d5 to a file also named README which contents are stored in object c9b319e.
21.8 A Glance At Our History
Let’s see a timeline of what we’ve done: $ git log commit 7b4977cdfb3f304feffa6fc22de1007dd2bebf26 Author: Lasse Schuirmann
README: Add usage instructions
commit ec6c903a0a18960cd73df18897e56738c4c6bb51 Author: Lasse Schuirmann
Add README
That looks fairly easy. However I cannot withstand to point out that despite commits look so fine, linearly arranged here, they are actually nothing more than commit objects, floating around in the .git/objects/ directory. So git log just looks where HEAD points to and recursively asks each commit what it’s parent is (if it has one). Since every good hitchhiker does know how to travel through time and change events, we’ll learn to do that in the next chapter ;)
74 Chapter 21. A Hitchhiker’s Guide to Git(1): Genesis coala Documentation, Release 0.5.2
21.9 Configuring Git Even Better
21.9.1 Better staging
It is worth to mention that git add also accepts directories as an argument. I.e. git add . recursively adds all files from the current directory. In order to generally ignore certain patterns of files (e.g. it’s bad practice to commit any generated stuff), one can write a .gitignore file. This file can look as follows: README~ # Ignore gedit temporary files *.o # Ignore compiled object files
The exact pattern is defined here: http://git-scm.com/docs/gitignore Files matching this pattern will: • Not be added with git add unless forced with -f • Not be shown in git status as unstaged It is usually a good idea to commit the .gitignore to the repository so all developers don’t need to care about those files.
21.9.2 Aliases
So, we’ve learned quite some stuff. However git command’s aren’t as intuitive as they could be sometimes. They could be shorter too. So let’s define us some aliases of the commands we know. The ones given here are only suggestions, you should choose the aliases in a way that suits best for you!
Aliasing Git Itself
If you’re using git much, you might want to add alias g=git to your .bashrc or .zshrc or whatever. (On windows you’re a bit screwed. But what did you expect? Really?)
Aliasing Git Commands
Let’s let git give us our editor since we don’t want to edit just one value: git config --global --edit
You can add aliases through the [alias] section, here are the aliases I suggest: [alias] a= add c= commit-v ca= commit-v-a d= diff dif= diff # Thats a typo :) i= init l= log st= status stat= status
21.9. Configuring Git Even Better 75 coala Documentation, Release 0.5.2
21.10 Conclusion
So what did we learn? We did some basic git commands: • git config: accessing git configuration • git init: creating a repository • git status: getting the current status of files, staging and so on • git add: staging files for the commit • git diff: showing the difference between the current commit and what we have on our file system • git commit: writing staged changes to a commit • git log: browsing history We also learned how git organizes commits, how it stores files and how we can make git ignore files explicitly. I hope this helped you understanding a bit what git does and what it is. The next tutorial will hopefully cover all the basics. (Some were already hinted here.)
76 Chapter 21. A Hitchhiker’s Guide to Git(1): Genesis CHAPTER 22
coalib
22.1 coalib package
22.1.1 Subpackages coalib.bearlib package
Subpackages coalib.bearlib.abstractions package
Submodules coalib.bearlib.abstractions.Lint module class coalib.bearlib.abstractions.Lint.Lint(*args, **kwargs) Bases: coalib.bears.Bear.Bear Deals with the creation of linting bears. For the tutorial see: http://coala.readthedocs.org/en/latest/Users/Tutorials/Linter_Bears.html Parameters • executable – The executable to run the linter. • prerequisite_command – The command to run as a prerequisite and is of type list. • prerequisites_fail_msg – The message to be displayed if the prerequisite fails. • arguments – The arguments to supply to the linter, such that the file name to be analyzed can be appended to the end. Note that we use .format() on the arguments - so, {abc} needs to be given as {{abc}}. Currently, the following will be replaced: – {filename} - The filename passed to lint() – {config_file} - The config file created using config_file() • output_regex – The regex which will match the output of the linter to get results. This is not used if gives_corrected is set. This regex should give out the following variables: – line - The line where the issue starts. – column - The column where the issue starts.
77 coala Documentation, Release 0.5.2
– end_line - The line where the issue ends. – end_column - The column where the issue ends. – severity - The severity of the issue. – message - The message of the result. – origin - The origin of the issue. • diff_severity – The severity to use for all results if gives_corrected is set. • diff_message – The message to use for all results if gives_corrected is set. • use_stderr – Uses stderr as the output stream is it’s True. • use_stdin – Sends file as stdin instead of giving the file name. • gives_corrected – True if the executable gives the corrected file or just the issues. • severity_map – A dict where the keys are the possible severity values the Linter gives out and the values are the severity of the coala Result to set it to. If it is not a dict, it is ignored. arguments = ‘’ classmethod check_prerequisites() Checks for prerequisites required by the Linter Bear. static config_file() Returns a configuation file from the section given to the bear. The section is available in self.section. To add the config file’s name generated by this function to the arguments, use {config_file}. Returns A list of lines of the config file to be used or None. diff_message = ‘No result message was set’ diff_severity = 1 executable = None generate_config_file() Generates a temporary config file. Note: The user of the function is responsible for deleting the tempfile when done with it. Returns The file name of the tempfile created. gives_corrected = False lint(filename=None, file=None) Takes a file and lints it using the linter variables defined apriori. Parameters • filename – The name of the file to execute. • file – The contents of the file as a list of strings. match_to_result(match, filename) Converts a regex match’s groups into a result. Parameters • match – The match got from regex parsing. • filename – The name of the file from which this match is got. output_regex = re.compile(‘(?P
78 Chapter 22. coalib coala Documentation, Release 0.5.2
prerequisite_command = None prerequisite_fail_msg = ‘Unknown failure.’ process_output(output, filename, file) severity_map = None use_stderr = False use_stdin = False coalib.bearlib.abstractions.SectionCreatable module class coalib.bearlib.abstractions.SectionCreatable.SectionCreatable Bases: object A SectionCreatable is an object that is creatable out of a section object. Thus this is the class for many helper objects provided by the bearlib. If you want to use an object that inherits from this class the following approach is recommended: Instantiate it via the from_section method. You can provide default arguments via the lower case keyword arguments. Example: SpacingHelper.from_section(section, tabwidth=8)
creates a SpacingHelper and if the “tabwidth” setting is needed and not contained in section, 8 will be taken. It is recommended to write the prototype of the __init__ method according to this example: def __init__(self, setting_one: int, setting_two: bool=False): pass # Implementation
This way the get_optional_settings and the get_non_optional_settings method will extract automatically that: •setting_one should be an integer •setting_two should be a bool and defaults to False If you write a documentation comment, you can use :param to add descriptions to your parameters. These will be available too automatically. classmethod from_section(section, **kwargs) Creates the object from a section object. Parameters • section – A section object containing at least the settings specified by get_non_optional_settings() • kwargs – Additional keyword arguments classmethod get_metadata() classmethod get_non_optional_settings() Retrieves the minimal set of settings that need to be defined in order to use this object. Returns a dictionary of needed settings as keys and help texts as values classmethod get_optional_settings() Retrieves the settings needed IN ADDITION to the ones of get_non_optional_settings to use this object without internal defaults. Returns a dictionary of needed settings as keys and help texts as values
22.1. coalib package 79 coala Documentation, Release 0.5.2
Module contents The abstractions package contains classes that serve as interfaces for helper classes in the bearlib.
coalib.bearlib.languages package
Subpackages
coalib.bearlib.languages.definitions package
Module contents This directory holds language definitions. Language definitions hold expressions that help defining specific syntax elements for a programming language. Currently defined keys are: names extensions comment_delimiter multiline_comment_delimiters string_delimiters multi- line_string_delimiters keywords special_chars coalib.bearlib.languages.documentation package
Submodules coalib.bearlib.languages.documentation.DocstyleDefinition module class coalib.bearlib.languages.documentation.DocstyleDefinition.DocstyleDefinition(*args, **kwargs) Bases: object The DocstyleDefinition class holds values that identify a certain type of documentation comment (for which language, documentation style/tool used etc.). docstyle The documentation style/tool used to document code. Returns A lower-case string defining the docstyle (i.e. “default” or “doxygen”). language The programming language. Returns A lower-case string defining the programming language (i.e. “cpp” or “python”). classmethod load(*args, **kwargs) markers A tuple of marker sets that identify a documentation comment. Marker sets consist of 3 entries where the first is the start-marker, the second one the each-line marker and the last one the end-marker. For example a marker tuple with a single marker set (("/**", "*", "*/"),) would match following documentation comment: /** * This is documentation. */
It’s also possible to supply an empty each-line marker (("/**", "", "*/")):
80 Chapter 22. coalib coala Documentation, Release 0.5.2
/** This is more documentation. */
Markers are matched “greedy”, that means it will match as many each-line markers as possible. I.e. for (“///”, “///”, “///”)): /// Brief documentation. /// /// Detailed documentation.
Returns A tuple of marker/delimiter string tuples that identify a documentation comment.
coalib.bearlib.languages.documentation.DocumentationComment module class coalib.bearlib.languages.documentation.DocumentationComment.DocumentationComment(documentation, marker, range) Bases: object The DocumentationComment holds information about a documentation comment inside source-code, like posi- tion etc. coalib.bearlib.languages.documentation.DocumentationExtraction module coalib.bearlib.languages.documentation.DocumentationExtraction.extract_documentation(content, lan- guage, doc- style) Extracts all documentation texts inside the given source-code-string using the coala docstyle definition files. The documentation texts are sorted by their order appearing in content. For more information about how documentation comments are identified and extracted, see DocstyleDefini- tion.doctypes enumeration. Parameters • content – The source-code-string where to extract documentation from. Needs to be a list or tuple where each string item is a single line (including ending whitespaces like n). • language – The programming language used. • docstyle – The documentation style/tool used (e.g. doxygen). Raises • FileNotFoundError – Raised when the docstyle definition file was not found. • KeyError – Raised when the given language is not defined in given docstyle. • ValueError – Raised when a docstyle definition setting has an invalid format. Returns An iterator returning each DocumentationComment found in the content. coalib.bearlib.languages.documentation.DocumentationExtraction.extract_documentation_with_markers(content, mark- ers) Extracts all documentation texts inside the given source-code-string. Parameters
22.1. coalib package 81 coala Documentation, Release 0.5.2
• content – The source-code-string where to extract documentation from. Needs to be a list or tuple where each string item is a single line (including ending whitespaces like n). • markers – The list/tuple of marker-sets that identify a documentation-comment. Low- index markers have higher priority than high-index markers. Returns An iterator returning each DocumentationComment found in the content.
Module contents Provides facilities to extract, parse and assemble documentation comments for different languages and documentation tools.
Submodules coalib.bearlib.languages.LanguageDefinition module class coalib.bearlib.languages.LanguageDefinition.LanguageDefinition(language_family: str, lan- guage: str) Bases: coalib.bearlib.abstractions.SectionCreatable.SectionCreatable
Module contents This directory holds means to get generic information for specific languages. coalib.bearlib.spacing package
Submodules coalib.bearlib.spacing.SpacingHelper module class coalib.bearlib.spacing.SpacingHelper.SpacingHelper(tab_width: int=4) Bases: coalib.bearlib.abstractions.SectionCreatable.SectionCreatable DEFAULT_TAB_WIDTH = 4 get_indentation(*args, **kwargs) replace_spaces_with_tabs(*args, **kwargs) replace_tabs_with_spaces(*args, **kwargs) yield_tab_lengths(*args, **kwargs)
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.
82 Chapter 22. coalib coala Documentation, Release 0.5.2 coalib.bears package
Submodules coalib.bears.BEAR_KIND module coalib.bears.Bear module class coalib.bears.Bear.Bear(*args, **kwargs) Bases: pyprint.Printer.Printer, coalib.output.printers.LogPrinter.LogPrinter A bear contains the actual subroutine that is responsible for checking source code for certain specifications. However it can actually do whatever it wants with the files it gets. If you are missing some Result type, feel free to contact us and/or help us extending the coalib. This is the base class for every bear. If you want to write an bear, you will probably want to look at the GlobalBear and LocalBear classes that inherit from this class. In any case you’ll want to overwrite at least the run method. You can send debug/warning/error messages through the debug(), warn(), err() functions. These will send the appropriate messages so that they are outputted. Be aware that if you use err(), you are expected to also terminate the bear run-through immediately. If you need some setup or teardown for your bear, feel free to overwrite the set_up() and tear_down() functions. They will be invoked before/after every run invocation. Settings are available at all times through self.section. classmethod check_prerequisites() Checks whether needed runtime prerequisites of the bear are satisfied. This function gets executed at construction and returns True by default. Section value requirements shall be checked inside the run method. Returns True if prerequisites are satisfied, else False or a string that serves a more detailed description of what’s missing. execute(*args, **kwargs) get_config_dir() Gives the directory where the configuration file is Returns Directory of the config file static get_dependencies() Retrieves bear classes that are to be executed before this bear gets executed. The results of these bears will then be passed to the run method as a dict via the dependency_results argument. The dict will have the name of the Bear as key and the list of its results as results. Returns A list of bear classes. classmethod get_metadata() Returns Metadata for the run function. However parameters like self or parameters implicitly used by coala (e.g. filename for local bears) are already removed. classmethod get_non_optional_settings() This method has to determine which settings are needed by this bear. The user will be prompted for needed settings that are not available in the settings file so don’t include settings where a default value would do. Returns A dictionary of needed settings as keys and a tuple of help text and annotation as values static kind()
22.1. coalib package 83 coala Documentation, Release 0.5.2
Returns The kind of the bear log_message(log_message, timestamp=None, **kwargs) classmethod missing_dependencies(lst) Checks if the given list contains all dependencies. Parameters lst – A list of all already resolved bear classes (not instances). Returns A list of missing dependencies. run(*args, dependency_results=None, **kwargs) run_bear_from_section(args, kwargs) coalib.bears.GlobalBear module class coalib.bears.GlobalBear.GlobalBear(file_dict, section, message_queue, timeout=0) Bases: coalib.bears.Bear.Bear A GlobalBear is able to analyze semantic facts across several file. The results of a GlobalBear will be presented grouped by the origin Bear. Therefore Results spanning above multiple files are allowed and will be handled right. If you only look at one file at once anyway a LocalBear is better for your needs. (And better for performance and usability for both user and developer.) static kind() run(*args, dependency_results=None, **kwargs) Handles all files in file_dict. Returns A list of Result type. coalib.bears.LocalBear module class coalib.bears.LocalBear.LocalBear(*args, **kwargs) Bases: coalib.bears.Bear.Bear A LocalBear is a Bear that analyzes only one file at once. It therefore can not analyze semantical facts over multiple files. This has the advantage that it can be highly parrallelized. In addition, the results from multiple bears for one file can be shown together for that file, which is better to grasp for the user. coala takes care of all that. Examples for LocalBear’s could be: •A SpaceConsistencyBear that checks every line for trailing whitespaces, tabs, etc. •A VariableNameBear that checks variable names and constant names for certain conditions classmethod get_metadata() static kind() run(filename, file, *args, dependency_results=None, **kwargs) Handles the given file. Parameters • filename – The filename of the file • file – The file contents as string array
84 Chapter 22. coalib coala Documentation, Release 0.5.2
Returns A list of Result
Module contents
coalib.collecting package
Submodules
coalib.collecting.Collectors module
coalib.collecting.Collectors.collect_all_bears_from_sections(sections, log_printer) Collect all kinds of bears from bear directories given in the sections. Parameters • bear_dirs – directory name or list of such that can contain bears • log_printer – log_printer to handle logging Returns tuple of dictionaries of local and global bears The dictionary key is section class and dic- tionary value is a list of Bear classes coalib.collecting.Collectors.collect_bears(bear_dirs, bear_globs, kinds, log_printer, warn_if_unused_glob=True) Collect all bears from bear directories that have a matching kind matching the given globs. Parameters • bear_dirs – Directory name or list of such that can contain bears. • bear_globs – Globs of bears to collect. • kinds – List of bear kinds to be collected. • log_printer – LogPrinter to handle logging. • warn_if_unused_glob – True if warning message should be shown if a glob didn’t give any bears. Returns Tuple of list of matching bear classes based on kind. The lists are in the same order as kinds. coalib.collecting.Collectors.collect_dirs(dir_paths, ignored_dir_paths=None) Evaluate globs in directory paths and return all matching directories Parameters • dir_paths – file path or list of such that can include globs • ignored_dir_paths – list of globs that match to-be-ignored dirs Returns list of paths of all matching directories coalib.collecting.Collectors.collect_files(file_paths, log_printer, ig- nored_file_paths=None, limit_file_paths=None) Evaluate globs in file paths and return all matching files Parameters • file_paths – file path or list of such that can include globs
22.1. coalib package 85 coala Documentation, Release 0.5.2
• ignored_file_paths – list of globs that match to-be-ignored files • limit_file_paths – list of globs that the files are limited to Returns list of paths of all matching files coalib.collecting.Collectors.collect_registered_bears_dirs(entrypoint) Searches setuptools for the entrypoint and returns the bear directories given by the module. Parameters entrypoint – The endpoint to find packages with. Returns List of bear directories. coalib.collecting.Dependencies module exception coalib.collecting.Dependencies.CircularDependencyError Bases: Exception classmethod for_bears(bears) Creates the CircularDependencyError with a helpful message about the dependency. coalib.collecting.Dependencies.resolve(bears) Collects all dependencies of the given bears. This will also remove duplicates. Parameters bears – The given bears. Will not be modified. Returns The new list of bears, sorted so that it can be executed sequentially without dependency issues.
coalib.collecting.Importers module
coalib.collecting.Importers.iimport_objects(file_paths, names=None, types=None, su- pers=None, attributes=None, local=False, verbose=False) Import all objects from the given modules that fulfill the requirements Parameters • file_paths – File path(s) from which objects will be imported • names – Name(s) an objects need to have one of • types – Type(s) an objects need to be out of • supers – Class(es) objects need to be a subclass of • attributes – Attribute(s) an object needs to (all) have • local – if True: Objects need to be defined in the file they appear in to be collected Returns iterator that yields all matching python objects Raises Exception – Any exception that is thrown in module code or an ImportError if paths are erroneous. coalib.collecting.Importers.import_objects(file_paths, names=None, types=None, su- pers=None, attributes=None, local=False, verbose=False) Import all objects from the given modules that fulfill the requirements Parameters • file_paths – File path(s) from which objects will be imported
86 Chapter 22. coalib coala Documentation, Release 0.5.2
• names – Name(s) an objects need to have one of • types – Type(s) an objects need to be out of • supers – Class(es) objects need to be a subclass of • attributes – Attribute(s) an object needs to (all) have • local – if True: Objects need to be defined in the file they appear in to be collected Returns list of all matching python objects Raises Exception – Any exception that is thrown in module code or an ImportError if paths are erroneous.
Module contents coalib.misc package
Submodules coalib.misc.BuildManPage module class coalib.misc.BuildManPage.BuildManPage(dist) Bases: distutils.cmd.Command Add a build_manpage command to your setup.py. To use this Command class add a command to call this class: # For setuptools setup( entry_points={ "distutils.commands":[ "build_manpage = coalib.misc.BuildManPage:BuildManPage" ] } )
# For distutils from coalib.misc.BuildManPage import BuildManPage setup( cmdclass={'build_manpage': BuildManPage} )
You can then use the following setup command to produce a man page: $ python setup.py build_manpage --output=coala.1 --parser=coalib.parsing.DefaultArgParser:default_arg_parser
If automatically want to build the man page every time you invoke your build, add to your ‘setup.cfg‘ the following: [build_manpage] output =
finalize_options() initialize_options() run()
22.1. coalib package 87 coala Documentation, Release 0.5.2
user_options = [(‘output=’, ‘O’, ‘output file’), (‘parser=’, None, ‘module path to an ArgumentParser instance(e.g. mymod:func, where func is a method or function which returnan arparse.ArgumentParser instance.’)] class coalib.misc.BuildManPage.ManPageFormatter(prog, indent_increment=2, max_help_position=24, width=None, desc=None, long_desc=None, ext_sections=None, parser=None) Bases: argparse.HelpFormatter format_man_page() coalib.misc.Constants module coalib.misc.ContextManagers module coalib.misc.ContextManagers.make_temp(suffix=’‘, prefix=’tmp’, dir=None) Creates a temporary file with a closed stream and deletes it when done. Returns A contextmanager retrieving the file path. coalib.misc.ContextManagers.prepare_file(lines, filename, force_linebreaks=True, cre- ate_tempfile=True, tempfile_kwargs={}) Can create a temporary file (if filename is None) with the lines. Can also add a trailing newline to each line specified if needed. Parameters • lines – The lines from the file. (list or tuple of strings) • filename – The filename to be prepared. • force_linebreaks – Whether to append newlines at each line if needed. • create_tempfile – Whether to save lines in tempfile if needed. • tempfile_kwargs – Kwargs passed to tempfile.mkstemp(). coalib.misc.ContextManagers.replace_stderr(replacement) Replaces stderr with the replacement, yields back to the caller and then reverts everything back. coalib.misc.ContextManagers.replace_stdout(replacement) Replaces stdout with the replacement, yields back to the caller and then reverts everything back. coalib.misc.ContextManagers.retrieve_stderr() Yields a StringIO object from which one can read everything that was printed to stderr. (It won’t be printed to the real stderr!) Example usage: with retrieve_stderr() as stderr: print(“something”) # Won’t print to the console what_was_printed = stderr.getvalue() # Save the value coalib.misc.ContextManagers.retrieve_stdout() Yields a StringIO object from which one can read everything that was printed to stdout. (It won’t be printed to the real stdout!) Example usage: with retrieve_stdout() as stdout: print(“something”) # Won’t print to the console what_was_printed = std- out.getvalue() # Save the value coalib.misc.ContextManagers.simulate_console_inputs(*inputs) Does some magic to simulate the given inputs to any calls to the input builtin. This yields back an InputGenerator object so you can check which input was already used and append any additional inputs you want. Example:
88 Chapter 22. coalib coala Documentation, Release 0.5.2
with simulate_console_inputs(0, 1, 2) as generator: assert(input() == 0) as- sert(generator.last_input == 0) generator.inputs.append(3) assert(input() == 1) assert(input() == 2) assert(input() == 3) assert(generator.last_input == 3)
Parameters inputs – Any inputs to simulate. Raises ValueError – Raised when was asked for more input but there’s no more provided.
coalib.misc.ContextManagers.subprocess_timeout(sub_process, seconds, kill_pg=False) Kill subprocess if the sub process takes more the than the timeout. Parameters • sub_process – The sub process to run. • seconds – The number of seconds to allow the test to run for. If set to 0 or a negative value, it waits indefinitely. Floats can be used to specify units smaller than seconds. • kill_pg – Boolean whether to kill the process group or only this process. (not applicable for windows) coalib.misc.ContextManagers.suppress_stdout() Suppresses everything going to stdout. coalib.misc.Decorators module coalib.misc.Decorators.arguments_to_lists(function) Decorator for a function that converts all arguments to lists. Parameters function – target function Returns target function with only lists as parameters coalib.misc.Decorators.enforce_signature(function) Enforces the signature of the function by throwing TypeError’s if invalid arguments are provided. The return value is not checked. You can annotate any parameter of your function with the desired type or a tuple of allowed types. If you annotate the function with a value, this value only will be allowed (useful especially for None). Example: >>> @enforce_signature ... def test(arg: bool, another: (int, None)): ... pass ... >>> test(True,5) >>> test(True, None)
Any string value for any parameter e.g. would then trigger a TypeError. Parameters function – The function to check. coalib.misc.Decorators.generate_eq(*members) Decorator that generates equality and inequality operators for the decorated class. The given members as well as the type of self and other will be taken into account. Note that this decorator modifies the given class in place! Parameters members – A list of members to compare for equality. coalib.misc.Decorators.generate_ordering(*members) Decorator that generates ordering operators for the decorated class based on the given member names. All ordering except equality functions will raise a TypeError when a comparison with an unrelated class is attempted.
22.1. coalib package 89 coala Documentation, Release 0.5.2
(Comparisons with child classes will thus work fine with the capabilities of the base class as python will choose the base classes comparison operator in that case.) Note that this decorator modifies the given class in place! Parameters members – A list of members to compare, ordered from high priority to low. I.e. if the first member is equal the second will be taken for comparison and so on. If a member is None it is considered smaller than any other value except None. coalib.misc.Decorators.generate_repr(*members) Decorator that binds an auto-generated __repr__() function to a class. The generated __repr__() function prints in following format:
90 Chapter 22. coalib coala Documentation, Release 0.5.2
Parameters dicts – The dictionaries to invert. Returns The inversed dictionary which merges all dictionaries into one. coalib.misc.DictUtilities.update_ordered_dict_key(dictionary, old_key, new_key) coalib.misc.Enum module coalib.misc.Enum.enum(*sequential, **named) coalib.misc.Exceptions module coalib.misc.Exceptions.get_exitcode(exception, log_printer=None)
coalib.misc.MutableValue module
class coalib.misc.MutableValue.MutableValue(val=None) Bases: object
coalib.misc.Shell module
coalib.misc.Shell.escape_path_argument(path, shell=’cmd’) Makes a raw path ready for using as parameter in a shell command (escapes illegal characters, surrounds with quotes etc.). Parameters • path – The path to make ready for shell. • shell – The shell platform to escape the path argument for. Possible values are “sh”, “powershell”, and “cmd” (others will be ignored and return the given path without modifi- cation). Returns The escaped path argument. coalib.misc.Shell.get_shell_type() Finds the current shell type based on the outputs of common pre-defined variables in them. This is useful to identify which sort of escaping is required for strings. Returns The shell type. This can be either “powershell” if Windows Powershell is detected, “cmd” if command prompt is been detected or “sh” if it’s neither of these. coalib.misc.Shell.prepare_string_argument(string, shell=’cmd’) Prepares a string argument for being passed as a parameter on shell. On sh this function effectively encloses the given string with quotes (either ‘’ or “”, depending on content). Parameters • string – The string to prepare for shell. • shell – The shell platform to prepare string argument for. If it is not “sh” it will be ignored and return the given string without modification. Returns The shell-prepared string.
22.1. coalib package 91 coala Documentation, Release 0.5.2
coalib.misc.Shell.run_interactive_shell_command(command, **kwargs) Runs a command in shell and provides stdout, stderr and stdin streams. This function creates a context manager that sets up the process, returns to caller, closes streams and waits for process to exit on leaving. The process is opened in universal_newlines mode. Parameters • command – The command to run on shell. • kwargs – Additional keyword arguments to pass to subprocess.Popen that is used to spawn the process (except shell, stdout, stderr, stdin and universal_newlines, a TypeError is raised then). Returns A context manager yielding the process started from the command. coalib.misc.Shell.run_shell_command(command, stdin=None, **kwargs) Runs a command in shell and returns the read stdout and stderr data. This function waits for the process to exit. Parameters • command – The command to run on shell. • stdin – Initial input to send to the process. • kwargs – Additional keyword arguments to pass to subprocess.Popen that is used to spawn the process (except shell, stdout, stderr, stdin and universal_newlines, a TypeError is raised then). Returns A tuple with (stdoutstring, stderrstring). coalib.misc.StringConverter module class coalib.misc.StringConverter.StringConverter(value, strip_whitespaces=True, list_delimiters=None, dict_delimiter=’:’, re- move_empty_iter_elements=True) Bases: object Converts strings to other things as needed. If you need some kind of string conversion that is not implemented here, consider adding it so everyone gets something out of it. keys() value
Module contents coalib.output package
Subpackages coalib.output.dbus package
Submodules
92 Chapter 22. coalib coala Documentation, Release 0.5.2 coalib.output.dbus.BuildDbusService module class coalib.output.dbus.BuildDbusService.BuildDbusService(dist) Bases: distutils.cmd.Command Add a build_dbus command to your setup.py. To use this Command class add a command to call this class: # For setuptools setup( entry_points={ "distutils.commands":[ "build_dbus =" "coalib.misc.BuildDbusService:BuildDbusService" ] } )
# For distutils from coalib.misc.BuildDbusService import BuildDbusService setup( cmdclass={'build_dbus': BuildDbusService} )
You can then use the following setup command to produce a dbus service: $ python setup.py build_dbus
finalize_options() initialize_options() run() user_options = [(‘output=’, ‘O’, ‘output file’)] coalib.output.dbus.DbusApp module class coalib.output.dbus.DbusApp.DbusApp(app_id, name=’‘) Bases: object Stores data about each client that connects to the DbusServer create_document(path) Create a new dbus document. Parameters • path – The path to the document to be created. • object_path – The dbus object path to use as the base for the document object path. • object_path – The connection to which the new ddocument object path should be added. Returns a DbusDocument object. dispose_document(path) Dispose of the document with the given path. It fails silently if the document does not exist. If there are no more documents in the app, the app is disposed. Parameters path – The path to the document.
22.1. coalib package 93 coala Documentation, Release 0.5.2 coalib.output.dbus.DbusDocument module class coalib.output.dbus.DbusDocument.DbusDocument(doc_id, path=’‘) Bases: dbus.service.Object Analyze() This method analyzes the document and sends back the result Returns The output is structure which has 3 items: - The exitcode from the analysis. - List of logs from the analysis. - List of information about each section that contains: • The name of the section. • Boolean which is true if all bears in the section executed successfully. • List of results where each result is a string dictionary which contains: id, origin, message, file, line_nr, severity FindConfigFile() This method uses the path of the document to identify a user config file for it Returns The config file path GetConfigFile() This method gets the config file which is being used Returns The config path which is being used SetConfigFile(config_file) This method sets the config file to use. It has to be an absolute path, as otherwise it is difficult to find it. Parameters config_file – The path fo the config file to use. This has to be an absolute path Returns The config path which has been used interface = ‘org.coala_analyzer.v1’ path static results_to_dbus_struct(section_result, section_name) Converts the result tuple given by execute_section() - which has dictionaries and classes inside it - into a purely array based format as dbus protocol only allows arrays. Parameters • section_result – The result tuple given by execute_section() for a section • section_name – The name of the section Returns The result for a section in the form of an array which is sendable through dbus. coalib.output.dbus.DbusServer module class coalib.output.dbus.DbusServer.DbusServer(bus, path, on_disconnected=None) Bases: dbus.service.Object CreateDocument(path, sender=None) Creates a DbusDocument if it doesn’t exist. Parameters • path – The path to the document. • sender – The client who created the dbus request - this is used as the DbusApp’s name. Returns a DbusDocument object.
94 Chapter 22. coalib coala Documentation, Release 0.5.2
DisposeDocument(path, sender=None) Disposes a DbusDocument if it exists. Fails silently if it does not exist. Parameters • path – The path to the document. • sender – The client who created the dbus request - this is used as the DbusApp’s name to search for the document in. create_app(appname) Create a new dbus app with the given appname. Parameters appname – The name of the app to be created. Returns a DbusApp object. create_document(app, path) Create a new dbus document. Parameters • app – The DbusApp the document is related to. • path – The path to the document to be created. Returns a DbusDocument object. dispose_app(appname) Dispose of the app with the given name. It fails silently if the app does not exist. If there are no more apps connected to the server, it calls the on_disconnected callback. Parameters appname – The name of the app to dispose of. dispose_document(app, path) Dispose of the document with the given path. It fails silently if the document does not exist. If there are no more documents in the app, the app is disposed. Parameters • app – The DbusApp the document is under. • path – The path to the document. get_or_create_app(appname) Get the dbus app with the given appname. If there does not exist any app with the given name, a new app is created and returned. Parameters appname – The name of the app to be created. Returns A DbusApp object. get_or_create_document(app, path) Get the dbus document with the given path. If there does not exist any document under the DbusApp with the given path, a new document is created and returned. Parameters • app – The DbusApp the document is under. • path – The path to the document to be created. Returns A DbusApp object. interface = ‘org.coala_analyzer.v1’
22.1. coalib package 95 coala Documentation, Release 0.5.2
Module contents This package holds dbus related objects. Dbus objects are used to communicate between coala and other applications using dbus. All dbus clients will first connect to the DbusServer, and request the DbusServer to create documents which can be analyzed. The DbusServer internally handles different clients separately so that it is possible for multiple clients to connect simultaneously. Once the client creates a document, the object path of the document is returned and the client can use it to analyze the document (which happens in the DbusDocument. coalib.output.printers package
Submodules coalib.output.printers.EspeakPrinter module class coalib.output.printers.EspeakPrinter.EspeakPrinter Bases: pyprint.Printer.Printer, pyprint.ClosableObject.ClosableObject coalib.output.printers.HTMLWriter module class coalib.output.printers.HTMLWriter.HTMLWriter(filename, indentation_per_tag=2, in- dentation=0) Bases: pyprint.ClosableObject.ClosableObject Printer for outputting HTML Log files. Parameters • filename – the name of the file to put the data into (string). • indentation_per_tag – spaces used to indent every subsequent HTML tag. Raises TypeError – if directory of given file doesn’t exist or in case of access problems. close_tag(tag_name) Function to close an open HTML tag. e.g.
Parameters tag_name – the name of HTML Tag to be written to output logfile. open_tag(tag_name) Function to open HTML tag. e.g.Parameters tag_name – the name of HTML Tag to written in the output logfile. write(*args) Function to write in the given output HTML log file. Parameters args – arbitrary number of arguments to be written to output logfile. write_comment(*comments) Function for writing HTML comments in the output HTML log files. Parameters comments – an arbitrary number of comments to add to the HTML log file write_tag(tag, content=’‘, **tagargs) Function for writing an HTML tag, along with the required tag attributes and content. Parameters • tag – HTML Tag for formatting the content. • content – content to output into the HTML Log file.
96 Chapter 22. coalib coala Documentation, Release 0.5.2
• tagargs – arbitrary HTML tag attributes mapped to their respective values. Ordering of the tags is not preserved. coalib.output.printers.LOG_LEVEL module coalib.output.printers.ListLogPrinter module class coalib.output.printers.ListLogPrinter.ListLogPrinter(log_level=2, times- tamp_format=’%X’) Bases: pyprint.Printer.Printer, coalib.output.printers.LogPrinter.LogPrinter A ListLogPrinter is a log printer which collects all LogMessages to a list so that the logs can be used at a later time. log_message(log_message, **kwargs) coalib.output.printers.LogPrinter module class coalib.output.printers.LogPrinter.LogPrinter(printer, log_level=1, times- tamp_format=’%X’) Bases: object The LogPrinter class allows to print log messages to an underlying Printer. This class is an adapter, means you can create a LogPrinter from every existing Printer instance. debug(*messages, delimiter=’ ‘, timestamp=None, **kwargs) err(*messages, delimiter=’ ‘, timestamp=None, **kwargs) info(*messages, delimiter=’ ‘, timestamp=None, **kwargs) log(log_level, message, timestamp=None, **kwargs) log_exception(message, exception, log_level=3, timestamp=None, **kwargs) If the log_level of the printer is greater than DEBUG, it prints only the message. If it is DEBUG or lower, it shows the message along with the traceback of the exception. Parameters • message – The message to print. • exception – The exception to print. • log_level – The log_level of this message (not used when logging the traceback. Tracebacks always have a level of DEBUG). • timestamp – The time at which this log occured. Defaults to the current time. • kwargs – Keyword arguments to be passed when logging the message (not used when logging the traceback). log_message(log_message, **kwargs) printer Returns the underlying printer where logs are printed to. warn(*messages, delimiter=’ ‘, timestamp=None, **kwargs)
22.1. coalib package 97 coala Documentation, Release 0.5.2 coalib.output.printers.StringPrinter module class coalib.output.printers.StringPrinter.StringPrinter Bases: pyprint.Printer.Printer This is a simple printer that prints everything to a string. clear() Clears the print string. string Gets the print string.
Module contents This package holds printer objects. Printer objects are general purpose and not tied to coala. If you need logging capabilities please take a look at the LogPrinter object which adds logging capabilities “for free” if used as base class for any other printer.
Submodules coalib.output.ConfWriter module class coalib.output.ConfWriter.ConfWriter(file_name, key_value_delimiters=(‘=’, ), com- ment_seperators=(‘#’, ), key_delimiters=(‘, ‘, ‘ ‘), section_name_surroundings=None, section_override_delimiters=(‘.’, ), unsav- able_keys=(‘save’, )) Bases: pyprint.ClosableObject.ClosableObject static is_comment(key) write_section(section) write_sections(sections) coalib.output.ConsoleInteraction module coalib.output.ConsoleInteraction.acquire_actions_and_apply(console_printer, log_printer, sec- tion, file_diff_dict, result, file_dict, cli_actions=None) Acquires applicable actions and applies them. Parameters • console_printer – Object to print messages on the console. • log_printer – Printer responsible for logging the messages. • section – Name of section to which the result belongs. • file_diff_dict – Dictionary containing filenames as keys and Diff objects as values. • result – A derivative of Result. • file_dict – A dictionary containing all files with filename as key. • cli_actions – The list of cli actions available.
98 Chapter 22. coalib coala Documentation, Release 0.5.2
coalib.output.ConsoleInteraction.acquire_settings(log_printer, settings_names_dict) This method prompts the user for the given settings. Parameters • log_printer – Printer responsible for logging the messages. • settings – a dictionary with the settings name as key and a list containing a description in [0] and the name of the bears who need this setting in [1] and following. Example: {"UseTabs":["describes whether tabs should be used instead of spaces", "SpaceConsistencyBear", "SomeOtherBear"]}
Returns a dictionary with the settings name as key and the given value as value.
coalib.output.ConsoleInteraction.ask_for_action_and_apply(log_printer, con- sole_printer, section, meta- data_list, action_dict, failed_actions, result, file_diff_dict, file_dict) Asks the user for an action and applies it. Parameters • log_printer – Printer responsible for logging the messages. • console_printer – Object to print messages on the console. • section – Currently active section. • metadata_list – Contains metadata for all the actions. • action_dict – Contains the action names as keys and their references as values. • failed_actions – A set of all actions that have failed. A failed action remains in the list until it is successfully executed. • result – Result corresponding to the actions. • file_diff_dict – If its an action which applies a patch, this contains the diff of the patch to be applied to the file with filename as keys. • file_dict – Dictionary with filename as keys and its contents as values. Returns Returns a boolean value. True will be returned, if it makes sense that the user may choose to execute another action, False otherwise. coalib.output.ConsoleInteraction.choose_action(console_printer, actions) Presents the actions available to the user and takes as input the action the user wants to choose. Parameters • console_printer – Object to print messages on the console. • actions – Actions available to the user. Returns Return choice of action of user. coalib.output.ConsoleInteraction.format_lines(lines, line_nr=’‘)
22.1. coalib package 99 coala Documentation, Release 0.5.2
coalib.output.ConsoleInteraction.get_action_info(section, action, failed_actions) Get all the required Settings for an action. It updates the section with the Settings. Parameters • section – The section the action corresponds to. • action – The action to get the info for. • failed_actions – A set of all actions that have failed. A failed action remains in the list until it is successfully executed. Returns Action name and the updated section. coalib.output.ConsoleInteraction.nothing_done(log_printer) Will be called after processing a coafile when nothing had to be done, i.e. no section was enabled/targeted. Parameters log_printer – A LogPrinter object. coalib.output.ConsoleInteraction.print_actions(console_printer, section, actions, failed_actions) Prints the given actions and lets the user choose. Parameters • console_printer – Object to print messages on the console. • actions – A list of FunctionMetadata objects. • failed_actions – A set of all actions that have failed. A failed action remains in the list until it is successfully executed. Returns A touple with the name member of the FunctionMetadata object chosen by the user and a Section containing at least all needed values for the action. If the user did choose to do nothing, return (None, None). coalib.output.ConsoleInteraction.print_affected_files(console_printer, log_printer, section, result, file_dict, color=True) Print all the afected files and affected lines within them. Parameters • console_printer – Object to print messages on the console. • log_printer – Printer responsible for logging the messages. • section – The section to which the results belong to. • result_list – List containing the results • file_dict – A dictionary containing all files with filename as key. • color – Boolean variable to print the results in color or not. Can be used for testing. coalib.output.ConsoleInteraction.print_affected_lines(console_printer, file_dict, sec- tion, sourcerange) coalib.output.ConsoleInteraction.print_bears(console_printer, bears, compress) Presents all bears being used in a stylized manner. Parameters • console_printer – Object to print messages on the console. • bears – Its a dictionary with bears as keys and list of sections containing those bears as values.
100 Chapter 22. coalib coala Documentation, Release 0.5.2
• compress – If set to true, output will be compressed (just show bear names as a list) coalib.output.ConsoleInteraction.print_lines(console_printer, file_dict, section, sourcerange) Prints the lines between the current and the result line. If needed they will be shortened. Parameters • console_printer – Object to print messages on the console. • file_dict – A dictionary containing all files as values with filenames as key. • sourcerange – The SourceRange object referring to the related lines to print. coalib.output.ConsoleInteraction.print_result(console_printer, log_printer, section, file_diff_dict, result, file_dict, interac- tive=True) Prints the result to console. Parameters • console_printer – Object to print messages on the console. • log_printer – Printer responsible for logging the messages. • section – Name of section to which the result belongs. • file_diff_dict – Dictionary containing filenames as keys and Diff objects as values. • result – A derivative of Result. • file_dict – A dictionary containing all files with filename as key. Interactive Variable to check wether or not to offer the user actions interactively. coalib.output.ConsoleInteraction.print_results(log_printer, section, result_list, file_dict, file_diff_dict, color=True) Print all the results in a section. Parameters • log_printer – Printer responsible for logging the messages. • section – The section to which the results belong to. • result_list – List containing the results • file_dict – A dictionary containing all files with filename as key. • file_diff_dict – A dictionary that contains filenames as keys and diff objects as val- ues. • color – Boolean variable to print the results in color or not. Can be used for testing. coalib.output.ConsoleInteraction.print_results_formatted(log_printer, section, re- sult_list, *args) coalib.output.ConsoleInteraction.print_results_no_input(log_printer, section, result_list, file_dict, file_diff_dict, color=True) Print all non interactive results in a section Parameters • log_printer – Printer responsible for logging the messages. • section – The section to which the results belong to. • result_list – List containing the results
22.1. coalib package 101 coala Documentation, Release 0.5.2
• file_dict – A dictionary containing all files with filename as key. • file_diff_dict – A dictionary that contains filenames as keys and diff objects as val- ues. • color – Boolean variable to print the results in color or not. Can be used for testing. coalib.output.ConsoleInteraction.print_section_beginning(console_printer, section) Will be called after initialization current_section in begin_section() Parameters • console_printer – Object to print messages on the console. • section – The section that will get executed now. coalib.output.ConsoleInteraction.print_spaces_tabs_in_unicode(console_printer, line, tab_dict, color, index=0) Prints the lines with tabs and spaces replaced by unicode symbols. Parameters • console_printer – The Printer object to print to. • line – The line-text to print to console_printer. • tab_dict – A dictionary containing the indices of tabs inside line as keys and the tab- length as values. • color – The color to print the line with (except for spaces and tabs. • index – The index from where to start the printing. coalib.output.ConsoleInteraction.require_setting(log_printer, setting_name, arr) This method is responsible for prompting a user about a missing setting and taking its value as input from the user. Parameters • log_printer – Printer responsible for logging the messages. • setting_name – Name od the setting missing • arr – a list containing a description in [0] and the name of the bears who need this setting in [1] and following. coalib.output.ConsoleInteraction.show_bear(console_printer, bear, sections, metadata) Display all information about a bear. Parameters • console_printer – Object to print messages on the console. • bear – The bear to be displayed. • sections – The sections to which the bear belongs. • metadata – Metadata about the bear. coalib.output.ConsoleInteraction.show_bears(local_bears, global_bears, compress, con- sole_printer) Extracts all the bears from each enabled section or the sections in the targets and passes a dictionary to the show_bears_callback method. Parameters
102 Chapter 22. coalib coala Documentation, Release 0.5.2
• local_bears – Dictionary of local bears with section names as keys and bear list as values. • global_bears – Dictionary of global bears with section names as keys and bear list as values. • compress – If set to true, output will be compressed (just show bear names as a list) • show_bears_callback – The callback that is used to print these bears. It will get one parameter holding bears as key and the list of section names where it’s used as values. coalib.output.ConsoleInteraction.show_enumeration(console_printer, title, items, inden- tation, no_items_text) This function takes as input an iterable object (preferably a list or a dict). And prints in a stylized format. If the iterable object is empty, it prints a specific statement give by the user. An e.g :
22.1. coalib package 103 coala Documentation, Release 0.5.2
• project – Path to the coafile the results belong to. • log_printer – The logger which logs errors. coalib.output.Tagging.get_tag_path(tag, project, log_printer) Creates a hash value that is used for tagging and creates a path for it. Parameters • tag – The name for the tag. • project – The related coafile. • log_printer – The logger which logs errors. Returns A path containing a hash as filename that identifies the given parameters. coalib.output.Tagging.get_tags_dir(log_printer) coalib.output.Tagging.load_tagged_results(tag, project, log_printer) Retrieves results previously stored with tag_results. Parameters • tag – The tag name. • project – Path to the coafile the results belong to. • log_printer – The logger which logs errors. Returns A results dictionary, as generated by coala. coalib.output.Tagging.tag_results(tag, project, results, log_printer) This method takes a tag provided from the user and saves the results dictionary output by coala to a file. That file is uniquely identified by the combined hash of the project (i.e. coafile) and the provided tag. Parameters • tag – Tag provided by user. • project – Path to the coafile the results belong to. • log_printer – The logger which logs errors. • results – Results dictionary generated by coala.
Module contents
coalib.parsing package
Subpackages
coalib.parsing.StringProcessing package
Submodules
coalib.parsing.StringProcessing.Core module coalib.parsing.StringProcessing.Core.escape(string, escape_chars, escape_with=’\\’) Escapes all chars given inside the given string. Parameters
104 Chapter 22. coalib coala Documentation, Release 0.5.2
• string – The string where to escape characters. • escape_chars – The string or Iterable that contains the characters to escape. Each char inside this string will be escaped in the order given. Duplicate chars are allowed. • escape_with – The string that should be used as escape sequence. Returns The escaped string. coalib.parsing.StringProcessing.Core.nested_search_in_between(begin, end, string, max_matches=0, re- move_empty_matches=False, use_regex=False) Searches for a string enclosed between a specified begin- and end-sequence. Also enclosed n are put into the result. Doesn’t handle escape sequences, but supports nesting. Nested sequences are ignored during the match. Means you get only the first nesting level returned. If you want to acquire more levels, just reinvoke this function again on the return value. Using the same begin- and end-sequence won’t match anything. Parameters • begin – A pattern that defines where to start matching. • end – A pattern that defines where to end matching. • string – The string where to search in. • max_matches – Defines the maximum number of matches. If 0 or less is provided, the number of splits is not limited. • remove_empty_matches – Defines whether empty entries should be removed from the result. An entry is considered empty if no inner match was performed (regardless of matched start and end patterns). • use_regex – Specifies whether to treat the begin and end patterns as regexes or simple strings. Returns An iterator returning the matched strings. coalib.parsing.StringProcessing.Core.position_is_escaped(string, position=None) Checks whether a char at a specific position of the string is preceded by an odd number of backslashes. Parameters • string – Arbitrary string • position – Position of character in string that should be checked Returns True if the character is escaped, False otherwise coalib.parsing.StringProcessing.Core.search_for(pattern, string, flags=0, max_match=0, use_regex=False) Searches for a given pattern in a string. Parameters • pattern – A pattern that defines what to match. • string – The string to search in. • flags – Additional flags to pass to the regex processor. • max_match – Defines the maximum number of matches to perform. If 0 or less is pro- vided, the number of splits is not limited.
22.1. coalib package 105 coala Documentation, Release 0.5.2
• use_regex – Specifies whether to treat the pattern as a regex or simple string. Returns An iterator returning MatchObject’s. coalib.parsing.StringProcessing.Core.search_in_between(begin, end, string, max_matches=0, re- move_empty_matches=False, use_regex=False) Searches for a string enclosed between a specified begin- and end-sequence. Also enclosed n are put into the result. Doesn’t handle escape sequences. Parameters • begin – A pattern that defines where to start matching. • end – A pattern that defines where to end matching. • string – The string where to search in. • max_matches – Defines the maximum number of matches. If 0 or less is provided, the number of matches is not limited. • remove_empty_matches – Defines whether empty entries should be removed from the result. An entry is considered empty if no inner match was performed (regardless of matched start and end patterns). • use_regex – Specifies whether to treat the begin and end patterns as regexes or simple strings. Returns An iterator returning InBetweenMatch objects that hold information about the matched begin, inside and end string matched. coalib.parsing.StringProcessing.Core.split(pattern, string, max_split=0, remove_empty_matches=False, use_regex=False) Splits the given string by the specified pattern. The return character (n) is not a natural split pattern (if you don’t specify it yourself). This function ignores escape sequences. Parameters • pattern – A pattern that defines where to split. • string – The string to split by the defined pattern. • max_split – Defines the maximum number of splits. If 0 or less is provided, the number of splits is not limited. • remove_empty_matches – Defines whether empty entries should be removed from the result. • use_regex – Specifies whether to treat the split pattern as a regex or simple string. Returns An iterator returning the split up strings. coalib.parsing.StringProcessing.Core.unescape(string) Trimms off all escape characters from the given string. Parameters string – The string to unescape. coalib.parsing.StringProcessing.Core.unescaped_rstrip(string) Strips whitespaces from the right side of given string that are not escaped. Parameters string – The string where to strip whitespaces from. Returns The right-stripped string.
106 Chapter 22. coalib coala Documentation, Release 0.5.2
coalib.parsing.StringProcessing.Core.unescaped_search_for(pattern, string, flags=0, max_match=0, use_regex=False) Searches for a given pattern in a string that is not escaped. Parameters • pattern – A pattern that defines what to match unescaped. • string – The string to search in. • flags – Additional flags to pass to the regex processor. • max_match – Defines the maximum number of matches to perform. If 0 or less is pro- vided, the number of splits is not limited. • use_regex – Specifies whether to treat the pattern as a regex or simple string. Returns An iterator returning MatchObject’s. coalib.parsing.StringProcessing.Core.unescaped_search_in_between(begin, end, string, max_matches=0, re- move_empty_matches=False, use_regex=False) Searches for a string enclosed between a specified begin- and end-sequence. Also enclosed n are put into the result. Handles escaped begin- and end-sequences (and so only patterns that are unescaped).
Warning: Using the escape character ‘’ in the begin- or end-sequences the function can return strange results. The backslash can interfere with the escaping regex-sequence used internally to match the enclosed string.
Parameters • begin – A regex pattern that defines where to start matching. • end – A regex pattern that defines where to end matching. • string – The string where to search in. • max_matches – Defines the maximum number of matches. If 0 or less is provided, the number of matches is not limited. • remove_empty_matches – Defines whether empty entries should be removed from the result. An entry is considered empty if no inner match was performed (regardless of matched start and end patterns). • use_regex – Specifies whether to treat the begin and end patterns as regexes or simple strings. Returns An iterator returning the matched strings. coalib.parsing.StringProcessing.Core.unescaped_split(pattern, string, max_split=0, remove_empty_matches=False, use_regex=False) Splits the given string by the specified pattern. The return character (n) is not a natural split pattern (if you don’t specify it yourself). This function handles escaped split-patterns (and so splits only patterns that are unescaped). Parameters • pattern – A pattern that defines where to split. • string – The string to split by the defined pattern.
22.1. coalib package 107 coala Documentation, Release 0.5.2
• max_split – Defines the maximum number of splits. If 0 or less is provided, the number of splits is not limited. • remove_empty_matches – Defines whether empty entries should be removed from the result. • use_regex – Specifies whether to treat the split pattern as a regex or simple string. Returns An iterator returning the split up strings. coalib.parsing.StringProcessing.Core.unescaped_strip(string) Strips whitespaces of the given string taking escape characters into account. Parameters string – The string where to strip whitespaces from. Returns The stripped string.
coalib.parsing.StringProcessing.Filters module coalib.parsing.StringProcessing.Filters.limit(iterator, count) A filter that removes all elements behind the set limit. Parameters • iterator – The iterator to be filtered. • count – The iterator limit. All elements at positions bigger than this limit are trimmed off. Exclusion: 0 or numbers below does not limit at all, means the passed iterator is completely yielded. coalib.parsing.StringProcessing.Filters.trim_empty_matches(iterator, groups=(0, )) A filter that removes empty match strings. It can only operate on iterators whose elements are of type MatchOb- ject. Parameters • iterator – The iterator to be filtered. • groups – An iteratable defining the groups to check for blankness. Only results are not yielded if all groups of the match are blank. You can not only pass numbers but also strings, if your MatchObject contains named groups. coalib.parsing.StringProcessing.InBetweenMatch module class coalib.parsing.StringProcessing.InBetweenMatch.InBetweenMatch(begin, inside, end) Bases: object Holds information about a match enclosed by two matches. begin end classmethod from_values(begin, begin_pos, inside, inside_pos, end, end_pos) Instantiates a new InBetweenMatch from Match values. This function allows to bypass the usage of Match object instantation: >>> a= InBetweenMatch(Match("A",0), Match("B",1), Match("C",2)) >>> b= InBetweenMatch.from_values("A",0,"B",1,"C",2) >>> assert a ==b
Parameters
108 Chapter 22. coalib coala Documentation, Release 0.5.2
• begin – The matched string from start pattern. • begin_pos – The position of the matched begin string. • inside – The matched string from inside/in-between pattern. • inside_pos – The position of the matched inside/in-between string. • end – The matched string from end pattern. • end_pos – The position of the matched end string. Returns An InBetweenMatch from the given values.
inside
coalib.parsing.StringProcessing.Match module class coalib.parsing.StringProcessing.Match.Match(match, position) Bases: object Stores information about a single textual match. end_position Marks the end position of the matched text (zero-based). Returns The end-position. match Returns the text matched. Returns The text matched. position Returns the position where the text was matched (zero-based). Returns The position. range Returns the position range where the text was matched. Returns A pair indicating the position range. The first element is the start position, the second one the end position.
Module contents
Submodules coalib.parsing.CliParsing module coalib.parsing.CliParsing.check_conflicts(sections) Checks if there are any conflicting aruments passed Returns True if no conflicts Raises SystemExit – If there are conflicting arguments (exit code: 2)
22.1. coalib package 109 coala Documentation, Release 0.5.2
coalib.parsing.CliParsing.parse_cli(arg_list=None, origin=’/home/docs/checkouts/readthedocs.org/user_builds/coala/checkouts/release- 0.5/docs’, arg_parser=None, key_value_delimiters=(‘=’, ‘:’), com- ment_seperators=(), key_delimiters=(‘, ‘, ), sec- tion_override_delimiters=(‘.’, )) Parses the CLI arguments and creates sections out of it. Parameters • arg_list – The CLI argument list. • origin – Directory used to interpret relative paths given as argument. • arg_parser – Instance of ArgParser that is used to parse none-setting arguments. • key_value_delimiters – Delimiters to separate key and value in setting arguments. • comment_seperators – Allowed prefixes for comments. • key_delimiters – Delimiter to separate multiple keys of a setting argument. • section_override_delimiters – The delimiter to delimit the section from the key name (e.g. the ‘.’ in sect.key = value). Returns A dictionary holding section names as keys and the sections themselves as value. coalib.parsing.CliParsing.parse_custom_settings(sections, custom_settings_list, origin, line_parser) Parses the custom settings given to coala via -S something=value. Parameters • sections – The Section dictionary to add to (mutable). • custom_settings_list – The list of settings strings. • origin – The originating directory. • line_parser – The LineParser to use. coalib.parsing.ConfParser module class coalib.parsing.ConfParser.ConfParser(key_value_delimiters=(‘=’, ), com- ment_seperators=(‘#’, ), key_delimiters=(‘, ‘, ‘ ‘), section_name_surroundings=None, remove_empty_iter_elements=True) Bases: object get_section(name, create_if_not_exists=False) parse(input_data, overwrite=False) Parses the input and adds the new data to the existing. Parameters • input_data – The filename to parse from. • overwrite – If True, wipes all existing Settings inside this instance and adds only the newly parsed ones. If False, adds the newly parsed data to the existing one (and overwrites already existing keys with the newly parsed values). Returns A dictionary with (lowercase) section names as keys and their Setting objects as values.
110 Chapter 22. coalib coala Documentation, Release 0.5.2
coalib.parsing.DefaultArgParser module
coalib.parsing.DefaultArgParser.default_arg_parser(formatter_class=None) This function creates an ArgParser to parse command line arguments. Parameters formatter_class – Formatting the arg_parser output into a specific form. For example: In the manpage format.
coalib.parsing.Globbing module
coalib.parsing.Globbing.fnmatch(name, patterns) Tests whether name matches pattern Parameters • name – File or directory name • patterns – Glob string with wildcards or list of globs Returns Boolean: Whether or not name is matched by pattern Glob Syntax: •‘[seq]’: Matches any character in seq. Cannot be empty. Any special character looses its special meaning in a set. •‘[!seq]’: Matches any character not in seq. Cannot be empty. Any special character looses its special meaning in a set. •‘(seq_a|seq_b)’: Matches either sequence_a or sequence_b as a whole. More than two or just one se- quence can be given. •‘?’: Matches any single character. •‘*’: Matches everything but os.sep. •‘**’: Matches everything. coalib.parsing.Globbing.glob(pattern) Iterates all filesystem paths that get matched by the glob pattern. Syntax is equal to that of fnmatch. Parameters pattern – Glob pattern with wildcards Returns List of all file names that match pattern coalib.parsing.Globbing.has_wildcard(pattern) Checks whether pattern has any wildcards. Parameters pattern – Glob pattern that may contain wildcards Returns Boolean: Whether or not there are wildcards in pattern coalib.parsing.Globbing.iglob(pattern) Iterates all filesystem paths that get matched by the glob pattern. Syntax is equal to that of fnmatch. Parameters pattern – Glob pattern with wildcards Returns Iterator that yields all file names that match pattern coalib.parsing.Globbing.relative_flat_glob(dirname, basename) Non-recursive glob for one directory. Does not accept wildcards. Parameters • dirname – Directory name
22.1. coalib package 111 coala Documentation, Release 0.5.2
• basename – Basename of a file in dir of dirname Returns List containing Basename if the file exists coalib.parsing.Globbing.relative_recursive_glob(dirname, pattern) Recursive Glob for one directory and all its (nested) subdirectories. Accepts only ‘**’ as pattern. Parameters • dirname – Directory name • pattern – The recursive wildcard ‘**’ Returns Iterator that yields all the (nested) subdirectories of the given dir coalib.parsing.Globbing.relative_wildcard_glob(dirname, pattern) Non-recursive glob for one directory. Accepts wildcards. Parameters • dirname – Directory name • pattern – Glob pattern with wildcards Returns List of files in the dir of dirname that match the pattern coalib.parsing.Globbing.translate(pattern) Translates a pattern into a regular expression. Parameters pattern – Glob pattern with wildcards Returns Regular expression with the same meaning coalib.parsing.LineParser module class coalib.parsing.LineParser.LineParser(key_value_delimiters=(‘=’, ), com- ment_seperators=(‘#’, ), key_delimiters=(‘, ‘, ), section_name_surroundings=None, sec- tion_override_delimiters=(‘.’, )) Bases: object parse(line) Note that every value in the returned touple besides the value is unescaped. This is so since the value is meant to be put into a Setting later thus the escapes may be needed there. Parameters line – the line to parse Returns section_name (empty string if it’s no section name), [(section_override, key), ...], value, comment
Module contents
The StringProcessing module contains various functions for extracting information out of strings. Most of them support regexes for advanced pattern matching. coalib.processes package
Subpackages
112 Chapter 22. coalib coala Documentation, Release 0.5.2 coalib.processes.communication package
Submodules coalib.processes.communication.LogMessage module class coalib.processes.communication.LogMessage.LogMessage(log_level, *messages, delimiter=’ ‘, times- tamp=None) Bases: object to_string_dict() Makes a dictionary which has all keys and values as strings and contains all the data that the LogMessage has. Returns Dictionary with keys and values as string.
Module contents
Submodules coalib.processes.BearRunning module coalib.processes.BearRunning.get_global_dependency_results(global_result_dict, bear_instance) This method gets all the results originating from the dependencies of a bear_instance. Each bear_instance may or may not have dependencies. Parameters global_result_dict – The list of results out of which the dependency results are picked. Returns None if bear has no dependencies, False if dependencies are not met, the dependency dict otherwise. coalib.processes.BearRunning.get_local_dependency_results(local_result_list, bear_instance) This method gets all the results originating from the dependencies of a bear_instance. Each bear_instance may or may not have dependencies. Parameters • local_result_list – The list of results out of which the dependency results are picked. • bear_instance – The instance of a local bear to get the dependencies from. Returns Return none if their are no dependencies for the bear. Else return a dictionary containing dependency results. coalib.processes.BearRunning.get_next_global_bear(timeout, global_bear_queue, global_bear_list, global_result_dict) Retrieves the next global bear. Parameters • timeout – The queue blocks at most timeout seconds for a free slot to execute the put operation on. After the timeout it returns queue Full exception.
22.1. coalib package 113 coala Documentation, Release 0.5.2
• global_bear_queue – queue (read, write) of indexes of global bear instances in the global_bear_list. • global_bear_list – A list containing all global bears to be executed. • global_result_dict – A Manager.dict that will be used to store global results. The list of results of one global bear will be stored with the bear name as key. Returns (bear, bearname, dependency_results) coalib.processes.BearRunning.run(file_name_queue, local_bear_list, global_bear_list, global_bear_queue, file_dict, local_result_dict, global_result_dict, message_queue, control_queue, time- out=0) This is the method that is actually runs by processes. If parameters type is ‘queue (read)’ this means it has to implement the get(timeout=TIMEOUT) method and it shall raise queue.Empty if the queue is empty up until the end of the timeout. If the queue has the (optional!) task_done() attribute, the run method will call it after processing each item. If parameters type is ‘queue (write)’ it shall implement the put(object, timeout=TIMEOUT) method. If the queues raise any exception not specified here the user will get an ‘unknown error’ message. So beware of that. Parameters • file_name_queue – queue (read) of file names to check with local bears. Each invoca- tion of the run method needs one such queue which it checks with all the local bears. The queue could be empty. (Repeat until queue empty.) • local_bear_list – List of local bear instances. • global_bear_list – List of global bear instances. • global_bear_queue – queue (read, write) of indexes of global bear instances in the global_bear_list. • file_dict – dict of all files as {filename:file}, file as in file.readlines(). • local_result_dict – A Manager.dict that will be used to store local results. A list of all local results. will be stored with the filename as key. • global_result_dict – A Manager.dict that will be used to store global results. The list of results of one global bear will be stored with the bear name as key. • message_queue – queue (write) for debug/warning/error messages (type LogMessage) • control_queue – queue (write). If any result gets written to the result_dict a tu- ple containing a CONTROL_ELEMENT (to indicate what kind of event happened) and either a bear name (for global results) or a file name to indicate the result will be put to the queue. If the run method finished all its local bears it will put (CON- TROL_ELEMENT.LOCAL_FINISHED, None) to the queue, if it finished all global ones, (CONTROL_ELEMENT.GLOBAL_FINISHED, None) will be put there. • timeout – The queue blocks at most timeout seconds for a free slot to execute the put operation on. After the timeout it returns queue Full exception. coalib.processes.BearRunning.run_bear(message_queue, timeout, bear_instance, *args, **kwargs) This method is responsible for executing the instance of a bear. It also reports or logs errors if any occur during the execution of that bear instance. Parameters
114 Chapter 22. coalib coala Documentation, Release 0.5.2
• message_queue – A queue that contains messages of type errors/warnings/debug state- ments to be printed in the Log. • timeout – The queue blocks at most timeout seconds for a free slot to execute the put operation on. After the timeout it returns queue Full exception. • bear_instance – The instance of the bear to be executed. • args – The arguments that are to be passed to the bear. • kwargs – The keyword arguments that are to be passed to the bear. Returns Returns a valid list of objects of the type Result if the bear executed succesfully. None otherwise. coalib.processes.BearRunning.run_global_bear(message_queue, timeout, global_bear_instance, depen- dency_results) Runs an instance of a global bear. Checks if bear_instance is of type GlobalBear and then passes it to the run_bear to execute. Parameters • message_queue – A queue that contains messages of type errors/warnings/debug state- ments to be printed in the Log. • timeout – The queue blocks at most timeout seconds for a free slot to execute the put operation on. After the timeout it returns queue Full exception. • global_bear_instance – Instance of GlobalBear to run. • dependency_results – The results of all the bears on which the instance of the passed bear to be run depends on. Returns Returns a list of results generated by the passed bear_instance. coalib.processes.BearRunning.run_global_bears(message_queue, timeout, global_bear_queue, global_bear_list, global_result_dict, control_queue) Run all global bears. Parameters • message_queue – A queue that contains messages of type errors/warnings/debug state- ments to be printed in the Log. • timeout – The queue blocks at most timeout seconds for a free slot to execute the put operation on. After the timeout it returns queue Full exception. • global_bear_queue – queue (read, write) of indexes of global bear instances in the global_bear_list. • global_bear_list – list of global bear instances • global_result_dict – A Manager.dict that will be used to store global results. The list of results of one global bear will be stored with the bear name as key. • control_queue – If any result gets written to the result_dict a tuple containing a CON- TROL_ELEMENT (to indicate what kind of event happened) and either a bear name(for global results) or a file name to indicate the result will be put to the queue. coalib.processes.BearRunning.run_local_bear(message_queue, timeout, local_result_list, file_dict, bear_instance, filename) Runs an instance of a local bear. Checks if bear_instance is of type LocalBear and then passes it to the run_bear to execute.
22.1. coalib package 115 coala Documentation, Release 0.5.2
Parameters • message_queue – A queue that contains messages of type errors/warnings/debug state- ments to be printed in the Log. • timeout – The queue blocks at most timeout seconds for a free slot to execute the put operation on. After the timeout it returns queue Full exception. • local_result_list – Its a list that stores the results of all local bears. • file_dict – Dictionary containing contents of file. • bear_instance – Instance of LocalBear the run. • filename – Name of the file to run it on. Returns Returns a list of results generated by the passed bear_instance. coalib.processes.BearRunning.run_local_bears(filename_queue, message_queue, timeout, file_dict, local_bear_list, local_result_dict, control_queue) Run local bears on all the files given. Parameters • filename_queue – queue (read) of file names to check with local bears. • message_queue – A queue that contains messages of type errors/warnings/debug state- ments to be printed in the Log. • timeout – The queue blocks at most timeout seconds for a free slot to execute the put operation on. After the timeout it returns queue Full exception. • file_dict – Dictionary that contains contents of files. • local_bear_list – List of local bears to run. • local_result_dict – A Manager.dict that will be used to store local bear results. A list of all local bear results will be stored with the filename as key. • control_queue – If any result gets written to the result_dict a tuple containing a CON- TROL_ELEMENT (to indicate what kind of event happened) and either a bear name(for global results) or a file name to indicate the result will be put to the queue. coalib.processes.BearRunning.run_local_bears_on_file(message_queue, timeout, file_dict, local_bear_list, lo- cal_result_dict, control_queue, filename) This method runs a list of local bears on one file. Parameters • message_queue – A queue that contains messages of type errors/warnings/debug state- ments to be printed in the Log. • timeout – The queue blocks at most timeout seconds for a free slot to execute the put operation on. After the timeout it returns queue Full exception. • file_dict – Dictionary that contains contents of files. • local_bear_list – List of local bears to run on file. • local_result_dict – A Manager.dict that will be used to store local bear results. A list of all local bear results will be stored with the filename as key.
116 Chapter 22. coalib coala Documentation, Release 0.5.2
• control_queue – If any result gets written to the result_dict a tuple containing a CON- TROL_ELEMENT (to indicate what kind of event happened) and either a bear name(for global results) or a file name to indicate the result will be put to the queue. • filename – The name of file on which to run the bears. coalib.processes.BearRunning.send_msg(message_queue, timeout, log_level, *args, delimiter=’ ‘, end=’‘) Puts message into message queue for a LogPrinter to present to the user. Parameters • message_queue – The queue to put the message into and which the LogPrinter reads. • timeout – The queue blocks at most timeout seconds for a free slot to execute the put operation on. After the timeout it returns queue Full exception. • log_level – The log_level i.e Error,Debug or Warning.It is sent to the LogPrinter de- pending on the message. • args – This includes the elements of the message. • delimiter – It is the value placed between each arg. By default it is a ‘ ‘. • end – It is the value placed at the end of the message. coalib.processes.BearRunning.task_done(obj) Invokes task_done if the given queue provides this operation. Otherwise passes silently. Parameters obj – Any object. coalib.processes.BearRunning.validate_results(message_queue, timeout, result_list, name, args, kwargs) Validates if the result_list passed to it contains valid set of results. That is the result_list must itself be a list and contain objects of the instance of Result object. If any irregularity is found a message is put in the message_queue to present the irregularity to the user. Each result_list belongs to an execution of a bear. Parameters • message_queue – A queue that contains messages of type errors/warnings/debug state- ments to be printed in the Log. • timeout – The queue blocks at most timeout seconds for a free slot to execute the put operation on. After the timeout it returns queue Full exception. • result_list – The list of results to validate. • name – The name of the bear executed. • args – The args with which the bear was executed. • kwargs – The kwargs with which the bear was executed. Returns Returns None if the result_list is invalid. Else it returns the result_list itself. coalib.processes.CONTROL_ELEMENT module coalib.processes.LogPrinterThread module class coalib.processes.LogPrinterThread.LogPrinterThread(message_queue, log_printer) Bases: threading.Thread
22.1. coalib package 117 coala Documentation, Release 0.5.2
This is the Thread object that outputs all log messages it gets from its message_queue. Setting obj.running = False will stop within the next 0.1 seconds. run() coalib.processes.Processing module coalib.processes.Processing.autoapply_actions(results, file_dict, file_diff_dict, section, log_printer) Auto-applies actions like defined in the given section. Parameters • results – A list of results. • file_dict – A dictionary containing the name of files and its contents. • file_diff_dict – A dictionary that contains filenames as keys and diff objects as val- ues. • section – The section. • log_printer – A log printer instance to log messages on. Returns A list of unprocessed results. coalib.processes.Processing.check_result_ignore(result, ignore_ranges) Determines if the result has to be ignored. Parameters • result – The result that needs to be checked. • ignore_ranges – A list of tuples, each containing a list of lower cased affected bear- names and a SourceRange to ignore. If any of the bearname lists is empty, it is considered an ignore range for all bears. This may be a list of globbed bear wildcards. Returns True if the result has to be ignored. coalib.processes.Processing.create_process_group(command_array, **kwargs) coalib.processes.Processing.execute_section(section, global_bear_list, local_bear_list, print_results, log_printer) Executes the section with the given bears. The execute_section method does the following things: 1.Prepare a Process - Load files - Create queues 2.Spawn up one or more Processes 3.Output results from the Processes 4.Join all processes
Parameters • section – The section to execute. • global_bear_list – List of global bears belonging to the section. • local_bear_list – List of local bears belonging to the section. • print_results – Prints all given results appropriate to the output medium. • log_printer – The log_printer to warn to.
118 Chapter 22. coalib coala Documentation, Release 0.5.2
Returns Tuple containing a bool (True if results were yielded, False otherwise), a Manager.dict containing all local results(filenames are key) and a Manager.dict containing all global bear results (bear names are key) as well as the file dictionary.
coalib.processes.Processing.fill_queue(queue_fill, any_list) Takes element from a list and populates a queue with those elements. Parameters • queue_fill – The queue to be filled. • any_list – List containing the elements. coalib.processes.Processing.filter_raising_callables(it, exception, *args, **kwargs) Filters all callable items inside the given iterator that raise the given exceptions. Parameters • it – The iterator to filter. • exception – The (tuple of) exception(s) to filter for. • args – Positional arguments to pass to the callable. • kwargs – Keyword arguments to pass to the callable. coalib.processes.Processing.get_cpu_count() coalib.processes.Processing.get_default_actions(section) Parses the key default_actions in the given section. Parameters section – The section where to parse from. Returns A dict with the bearname as keys and their default actions as values and another dict that contains bears and invalid action names. coalib.processes.Processing.get_file_dict(filename_list, log_printer) Reads all files into a dictionary. Parameters • filename_list – List of names of paths to files to get contents of. • log_printer – The logger which logs errors. Returns Reads the content of each file into a dictionary with filenames as keys. coalib.processes.Processing.get_ignore_scope(line, keyword) Retrieves the bears that are to be ignored defined in the given line. Parameters • line – The line containing the ignore declaration. • keyword – The keyword that was found. Everything after the rightmost occurrence of it will be considered for the scope. Returns A list of lower cased bearnames or an empty list (-> “all”) coalib.processes.Processing.get_running_processes(processes) coalib.processes.Processing.instantiate_bears(section, local_bear_list, global_bear_list, file_dict, message_queue) Instantiates each bear with the arguments it needs. Parameters • section – The section the bears belong to.
22.1. coalib package 119 coala Documentation, Release 0.5.2
• local_bear_list – List of local bear classes to instantiate. • global_bear_list – List of global bear classes to instantiate. • file_dict – Dictionary containing filenames and their contents. • message_queue – Queue responsible to maintain the messages delivered by the bears. Returns The local and global bear instance lists. coalib.processes.Processing.instantiate_processes(section, local_bear_list, global_bear_list, job_count, log_printer) Instantiate the number of processes that will run bears which will be responsible for running bears in a multi- processing environment. Parameters • section – The section the bears belong to. • local_bear_list – List of local bears belonging to the section. • global_bear_list – List of global bears belonging to the section. • job_count – Max number of processes to create. • log_printer – The log printer to warn to. Returns A tuple containing a list of processes, and the arguments passed to each process which are the same for each object. coalib.processes.Processing.print_result(results, file_dict, retval, print_results, section, log_printer, file_diff_dict, ignore_ranges) Takes the results produced by each bear and gives them to the print_results method to present to the user. Parameters • results – A list of results. • file_dict – A dictionary containing the name of files and its contents. • retval – It is True if no results were yielded ever before. If it is False this function will return False no matter what happens. Else it depends on if this invocation yields results. • print_results – A function that prints all given results appropriate to the output medium. • file_diff_dict – A dictionary that contains filenames as keys and diff objects as val- ues. • ignore_ranges – A list of SourceRanges. Results that affect code in any of those ranges will be ignored. Returns Returns False if any results were yielded. Else True. coalib.processes.Processing.process_queues(processes, control_queue, local_result_dict, global_result_dict, file_dict, print_results, sec- tion, log_printer) Iterate the control queue and send the results recieved to the print_result method so that they can be presented to the user. Parameters • processes – List of processes which can be used to run Bears. • control_queue – Containing control elements that indicate whether there is a result available and which bear it belongs to.
120 Chapter 22. coalib coala Documentation, Release 0.5.2
• local_result_dict – Dictionary containing results respective to local bears. It is modified by the processes i.e. results are added to it by multiple processes. • global_result_dict – Dictionary containing results respective to global bears. It is modified by the processes i.e. results are added to it by multiple processes. • file_dict – Dictionary containing file contents with filename as keys. • print_results – Prints all given results appropriate to the output medium. Returns Return True if all bears execute succesfully and Results were delivered to the user. Else False. coalib.processes.Processing.simplify_section_result(section_result) Takes in a section’s result from execute_section and simplifies it for easy usage in other functions. Parameters section_result – The result of a section which was executed. Returns Tuple containing: - bool - True if results were yielded - bool - True if unfixed results were yielded - list - Results from all bears (local and global) coalib.processes.Processing.yield_ignore_ranges(file_dict) Yields tuples of affected bears and a SourceRange that shall be ignored for those. Parameters file_dict – The file dictionary.
Module contents coalib.results package
Subpackages coalib.results.result_actions package
Submodules coalib.results.result_actions.ApplyPatchAction module class coalib.results.result_actions.ApplyPatchAction.ApplyPatchAction Bases: coalib.results.result_actions.ResultAction.ResultAction apply(result, original_file_dict, file_diff_dict, no_orig: bool=False) Apply the patch automatically. Parameters no_orig – Wether or not to create .orig backup files static is_applicable(result, original_file_dict, file_diff_dict) success_message = ‘Patch applied successfully.’ coalib.results.result_actions.OpenEditorAction module class coalib.results.result_actions.OpenEditorAction.OpenEditorAction Bases: coalib.results.result_actions.ApplyPatchAction.ApplyPatchAction apply(result, original_file_dict, file_diff_dict, editor: str) Open the affected file(s) in an editor. Parameters editor – The editor to open the file with. static is_applicable(result, original_file_dict, file_diff_dict)
22.1. coalib package 121 coala Documentation, Release 0.5.2
success_message = ‘Changes saved successfully.’ coalib.results.result_actions.PrintDebugMessageAction module class coalib.results.result_actions.PrintDebugMessageAction.PrintDebugMessageAction Bases: coalib.results.result_actions.ResultAction.ResultAction apply(result, original_file_dict, file_diff_dict) Print the debug message of the result. static is_applicable(result, original_file_dict, file_diff_dict) coalib.results.result_actions.ResultAction module A ResultAction is an action that is applicable to at least some results. This file serves the base class for all result actions, thus providing a unified interface for all actions. class coalib.results.result_actions.ResultAction.ResultAction Bases: object apply(result, original_file_dict, file_diff_dict, **kwargs) This action has no description although it should. Probably something went wrong. apply_from_section(*args, **kwargs) classmethod get_metadata() Retrieves metadata for the apply function. The description may be used to advertise this action to the user. The parameters and their help texts are additional information that are needed from the user. You can create a section out of the inputs from the user and use apply_from_section to apply :return A FunctionMetadata object. static is_applicable(result, original_file_dict, file_diff_dict) Checks whether the Action is valid for the result type. Returns True by default. Parameters • result – The result from the coala run to check if an Action is applicable. • original_file_dict – A dictionary containing the files in the state where the result was generated. • file_diff_dict – A dictionary containing a diff for every file from the state in the original_file_dict to the current state. This dict will be altered so you do not need to use the return value. success_message = ‘The action was executed successfully.’ coalib.results.result_actions.ShowPatchAction module class coalib.results.result_actions.ShowPatchAction.ShowPatchAction Bases: coalib.results.result_actions.ResultAction.ResultAction apply(result, original_file_dict, file_diff_dict, colored: bool=True) Print a diff of the patch that would be applied. Parameters colored – Wether or not to use colored output. static is_applicable(result, original_file_dict, file_diff_dict) success_message = ‘Displayed patch successfully.’
122 Chapter 22. coalib coala Documentation, Release 0.5.2
coalib.results.result_actions.ShowPatchAction.format_line(line, real_nr=’‘, sign=’|’, mod_nr=’‘, symbol=’‘) coalib.results.result_actions.ShowPatchAction.print_beautified_diff(difflines, printer)
Module contents The result_actions package holds objects deriving from ResultAction. A ResultAction represents an action that an be applied to a result.
Submodules
coalib.results.Diff module
class coalib.results.Diff.Diff(file_list) Bases: object A Diff result represents a difference for one file. add_lines(line_nr_before, lines) Adds lines after the given line number. Parameters • line_nr_before – Line number of the line before the additions. Use 0 for insert lines before everything. • lines – A list of lines to add. affected_code(filename) Creates a list of SourceRange objects which point to the related code. Changes on continuous lines will be put into one SourceRange. Parameters filename – The filename to associate the SourceRange’s to. Returns A list of all related SourceRange objects. change_line(line_nr, original_line, replacement) Changes the given line with the given line number. The replacement will be there instead. delete_line(line_nr) Mark the given line nr as deleted. The first line is line number 1. classmethod from_clang_fixit(fixit, file) Creates a Diff object from a given clang fixit and the file contents. Parameters • fixit – A cindex.Fixit object. • file – A list of lines in the file to apply the fixit to. Returns The corresponding Diff object. classmethod from_string_arrays(file_array_1, file_array_2) Creates a Diff object from two arrays containing strings. If this Diff is applied to the original array, the second array will be created. Parameters • file_array_1 – Original array
22.1. coalib package 123 coala Documentation, Release 0.5.2
• file_array_2 – Array to compare modified Calculates the modified file, after applying the Diff to the original. original Retrieves the original file. range(filename) Calculates a SourceRange spanning over the whole Diff. If something is added after the 0th line (i.e. before the first line) the first line will be included in the SourceRange. Parameters filename – The filename to associate the SourceRange with. Returns A SourceRange object. split_diff() Splits this diff into small pieces, such that several continuously altered lines are still together in one diff. All subdiffs will be yielded. unified_diff Generates a unified diff corresponding to this patch. Note that the unified diff is not deterministic and thus not suitable for equality comparison. coalib.results.HiddenResult module class coalib.results.HiddenResult.HiddenResult(origin, contents) Bases: coalib.results.Result.Result This is a result that is not meant to be shown to the user. It can be used to transfer any data from a dependent bear to others. coalib.results.LineDiff module exception coalib.results.LineDiff.ConflictError Bases: Exception class coalib.results.LineDiff.LineDiff(change=False, delete=False, add_after=False) Bases: object A LineDiff holds the difference between two strings. add_after change delete coalib.results.RESULT_SEVERITY module coalib.results.Result module class coalib.results.Result.Result(*args, **kwargs) Bases: object A result is anything that has an origin and a message. Optionally it might affect a file.
124 Chapter 22. coalib coala Documentation, Release 0.5.2
apply(*args, **kwargs) classmethod from_values(*args, **kwargs) location_repr() Retrieves a string, that briefly represents the affected code of the result. Returns A string containing all of the affected files seperated by a comma. overlaps(ranges) Determines if the result overlaps with source ranges provided. Parameters ranges – A list SourceRange objects to check for overlap. Returns True if the ranges overlap with the result. to_string_dict() Makes a dictionary which has all keys and values as strings and contains all the data that the base Result has. FIXME: diffs are not serialized ATM. FIXME: Only the first SourceRange of affected_code is serialized. If there are more, this data is currently missing. Returns Dictionary with keys and values as string. coalib.results.ResultFilter module coalib.results.ResultFilter.basics_match(original_result, modified_result) Checks whether the following properties of two results match: * origin * message * severity * debug_msg Parameters • original_result – A result of the old files • modified_result – A result of the new files Returns Boolean value whether or not the properties match coalib.results.ResultFilter.filter_results(original_file_dict, modified_file_dict, origi- nal_results, modified_results) Filters results for such ones that are unique across file changes Parameters • original_file_dict – Dict of lists of file contents before changes • modified_file_dict – Dict of lists of file contents after changes • original_results – List of results of the old files • modified_results – List of results of the new files Returns List of results from new files that are unique from all those that existed in the old changes coalib.results.ResultFilter.remove_range(file_contents, source_range) removes the chars covered by the sourceRange from the file Parameters • file_contents – list of lines in the file • source_range – Source Range Returns list of file contents without specified chars removed
22.1. coalib package 125 coala Documentation, Release 0.5.2
coalib.results.ResultFilter.remove_result_ranges_diffs(result_list, file_dict) Calculates the diffs to all files in file_dict that describe the removal of each respective result’s affected code. Parameters • result_list – list of results • file_dict – dict of file contents Returns returnvalue[result][file] is a diff of the changes the removal of this result’s affected code would cause for the file. coalib.results.ResultFilter.source_ranges_match(original_file_dict, diff_dict, original_result_diff_dict, modi- fied_result_diff_dict) Checks whether the SourceRanges of two results match Parameters • original_file_dict – Dict of lists of file contents before changes • diff_dict – Dict of diffs describing the changes per file • original_result_diff_dict – diff for each file for this result • modified_result_diff_dict – guess Returns Boolean value whether the SourceRanges match
coalib.results.SourcePosition module
class coalib.results.SourcePosition.SourcePosition(*args, **kwargs) Bases: coalib.results.TextPosition.TextPosition file
coalib.results.SourceRange module
class coalib.results.SourceRange.SourceRange(*args, **kwargs) Bases: coalib.results.TextRange.TextRange expand(file_contents) Passes a new SourceRange that covers the same area of a file as this one would. All values of None get replaced with absolute values. values of None will be interpreted as follows: self.start.line is None: -> 1 self.start.column is None: -> 1 self.end.line is None: -> last line of file self.end.column is None: -> last column of self.end.line Parameters file_contents – File contents of the applicable file Returns TextRange with absolute values file classmethod from_clang_range(range) Creates a SourceRange from a clang SourceRange object. Parameters range – A cindex.SourceRange object. classmethod from_values(file, start_line=None, start_column=None, end_line=None, end_column=None)
126 Chapter 22. coalib coala Documentation, Release 0.5.2
coalib.results.TextPosition module class coalib.results.TextPosition.TextPosition(*args, **kwargs) Bases: object column line coalib.results.TextRange module class coalib.results.TextRange.TextRange(*args, **kwargs) Bases: object end expand(text_lines) Passes a new TextRange that covers the same area of a file as this one would. All values of None get replaced with absolute values. values of None will be interpreted as follows: self.start.line is None: -> 1 self.start.column is None: -> 1 self.end.line is None: -> last line of file self.end.column is None: -> last column of self.end.line Parameters text_lines – File contents of the applicable file Returns TextRange with absolute values classmethod from_values(start_line=None, start_column=None, end_line=None, end_column=None) Creates a new TextRange. Parameters • start_line – The line number of the start position. The first line is 1. • start_column – The column number of the start position. The first column is 1. • end_line – The line number of the end position. If this parameter is None, then the end position is set the same like start position and end_column gets ignored. • end_column – The column number of the end position. Returns A TextRange. classmethod join(a, b) Creates a new TextRange that covers the area of two overlapping ones Parameters • a – TextRange (needs to overlap b) • b – TextRange (needs to overlap a) Returns A new TextRange covering the union of the Area of a and b overlaps(other) start
22.1. coalib package 127 coala Documentation, Release 0.5.2
Module contents coalib.settings package
Submodules coalib.settings.ConfigurationGathering module coalib.settings.ConfigurationGathering.find_user_config(file_path, max_trials=10) Uses the filepath to find the most suitable user config file for the file by going down one directory at a time and finding config files there. Parameters • file_path – The path of the file whose user config needs to be found • max_trials – The maximum number of directories to go down to. Returns The config file’s path coalib.settings.ConfigurationGathering.gather_configuration(acquire_settings, log_printer, au- toapply=None, arg_list=None) Loads all configuration files, retrieves bears and all needed settings, saves back if needed and warns about non-existent targets. This function: •Reads and merges all settings in sections from –Default config –User config –Configuration file –CLI •Collects all the bears •Fills up all needed settings •Writes back the new sections to the configuration file if needed •Gives all information back to caller
Parameters • acquire_settings – The method to use for requesting settings. It will get a parameter which is a dictionary with the settings name as key and a list containing a description in [0] and the names of the bears who need this setting in all following indexes. • log_printer – The log printer to use for logging. The log level will be adjusted to the one given by the section. • autoapply – Set whether to autoapply patches. This is overridable via any configuration file/CLI. • arg_list – CLI args to use Returns A tuple with the following contents:
128 Chapter 22. coalib coala Documentation, Release 0.5.2
• A dictionary with the sections • Dictionary of list of local bears for each section • Dictionary of list of global bears for each section • The targets list
coalib.settings.ConfigurationGathering.get_config_directory(section) coalib.settings.ConfigurationGathering.load_config_file(filename, log_printer, silent=False) Loads sections from a config file. Prints an appropriate warning if it doesn’t exist and returns a section dict containing an empty default section in that case. It assumes that the cli_sections are available. Parameters • filename – The file to load settings from. • log_printer – The log printer to log the warning/error to (in case). • silent – Whether or not to warn the user/exit if the file doesn’t exist. Raises SystemExit – Exits when given filename is invalid and is not the default coafile. Only raised when silent is False. coalib.settings.ConfigurationGathering.load_configuration(arg_list, log_printer) Parses the CLI args and loads the config file accordingly, taking default_coafile and the users .coarc into account. Parameters • arg_list – The list of command line arguments. • log_printer – The LogPrinter object for logging. Returns A tuple holding (log_printer: LogPrinter, sections: dict(str, Section), targets: list(str)). (Types indicated after colon.) coalib.settings.ConfigurationGathering.merge_section_dicts(lower, higher) Merges the section dictionaries. The values of higher will take precedence over the ones of lower. Lower will hold the modified dict in the end. Parameters • lower – A section. • higher – A section which values will take precedence over the ones from the other. Returns The merged dict. coalib.settings.ConfigurationGathering.save_sections(sections) Saves the given sections if they are to be saved. Parameters sections – A section dict. coalib.settings.ConfigurationGathering.warn_nonexistent_targets(targets, sections, log_printer) Prints out a warning on the given log printer for all targets that are not existent within the given sections. Parameters • targets – The targets to check. • sections – The sections to search. (Dict.)
22.1. coalib package 129 coala Documentation, Release 0.5.2
• log_printer – The log printer to warn to. coalib.settings.DocumentationComment module class coalib.settings.DocumentationComment.DocumentationComment(desc, param_dict, retval_desc) Bases: object classmethod from_docstring(docstring) Parses a python docstring. Usable attributes are: :param @param :return @return coalib.settings.FunctionMetadata module class coalib.settings.FunctionMetadata.FunctionMetadata(name, desc=’‘, retval_desc=’‘, non_optional_params=None, optional_params=None, omit=frozenset()) Bases: object create_params_from_section(section) Create a params dictionary for this function that holds all values the function needs plus optional ones that are available. Parameters section – The section to retrieve the values from. Returns The params dictionary. classmethod from_function(func, omit=frozenset()) Creates a FunctionMetadata object from a function. Please note that any variable argument lists are not supported. If you do not want the first (usual named ‘self’) argument to appear please pass the method of an actual INSTANCE of a class; passing the method of the class isn’t enough. Alternatively you can add “self” to the omit set. Parameters • func – The function. If __metadata__ of the unbound function is present it will be copied and used, otherwise it will be generated. • omit – A set of parameter names that are to be ignored. Returns The FunctionMetadata object corresponding to the given function. non_optional_params Retrieves a dict containing the name of non optional parameters as the key and a tuple of a description and the python annotation. Values that are present in self.omit will be omitted. optional_params Retrieves a dict containing the name of optional parameters as the key and a tuple of a description, the python annotation and the default value. Values that are present in self.omit will be omitted. str_nodesc = ‘No description given.’ str_optional = “Optional, defaults to ‘{}’.”
130 Chapter 22. coalib coala Documentation, Release 0.5.2
coalib.settings.Section module class coalib.settings.Section.Section(name, defaults=None) Bases: object This class holds a set of settings. add_or_create_setting(setting, custom_key=None, allow_appending=True) Adds the value of the setting to an existing setting if there is already a setting with the key. Otherwise creates a new setting. append(setting, custom_key=None) bear_dirs() copy() Returns a deep copy of this object delete_setting(key) Delete a setting :param key: The key of the setting to be deleted get(key, default=’‘, ignore_defaults=False) Retrieves the item without raising an exception. If the item is not available an appropriate Setting will be generated from your provided default value. Parameters • key – The key of the setting to return. • default – The default value • ignore_defaults – Whether or not to ignore the default section. Returns The setting. is_enabled(targets) Checks if this section is enabled or, if targets is not empty, if it is included in the targets list. Parameters targets – List of target section names, all lower case. Returns True or False update(other_section, ignore_defaults=False) Incorporates all keys and values from the other section into this one. Values from the other section override the ones from this one. Default values from the other section override the default values from this only. Parameters • other_section – Another Section • ignore_defaults – If set to true, do not take default values from other Returns self update_setting(key, new_key=None, new_value=None) Updates a setting with new values. :param key: The old key string. :param new_key: The new key string. :param new_value: The new value for the setting coalib.settings.Section.append_to_sections(sections, key, value, origin, sec- tion_name=None, from_cli=False) Appends the given data as a Setting to a Section with the given name. If the Section does not exist before it will be created empty.
22.1. coalib package 131 coala Documentation, Release 0.5.2
Parameters • sections – The sections dictionary to add to. • key – The key of the setting to add. • value – The value of the setting to add. • origin – The origin value of the setting to add. • section_name – The name of the section to add to. • from_cli – Whether or not this data comes from the CLI. coalib.settings.SectionFilling module coalib.settings.SectionFilling.fill_section(section, acquire_settings, log_printer, bears) Retrieves needed settings from given bears and asks the user for missing values. If a setting is requested by several bears, the help text from the latest bear will be taken. Parameters • section – A section containing available settings. Settings will be added if some are missing. • acquire_settings – The method to use for requesting settings. It will get a parameter which is a dictionary with the settings name as key and a list containing a description in [0] and the names of the bears who need this setting in all following indexes. • log_printer – The log printer for logging. • bears – All bear classes or instances. Returns The new section. coalib.settings.SectionFilling.fill_settings(sections, acquire_settings, log_printer) Retrieves all bears and requests missing settings via the given acquire_settings method. Parameters • sections – The sections to fill up, modified in place. • acquire_settings – The method to use for requesting settings. It will get a parameter which is a dictionary with the settings name as key and a list containing a description in [0] and the names of the bears who need this setting in all following indexes. • log_printer – The log printer to use for logging. Returns A tuple containing (local_bears, global_bears), each of them being a dictionary with the section name as key and as value the bears as a list. coalib.settings.Setting module class coalib.settings.Setting.Setting(key, value, origin=’‘, strip_whitespaces=True, list_delimiters=(‘, ‘, ‘;’), from_cli=False, re- move_empty_iter_elements=True) Bases: coalib.misc.StringConverter.StringConverter A Setting consists mainly of a key and a value. It mainly offers many conversions into common data types. key
132 Chapter 22. coalib coala Documentation, Release 0.5.2 coalib.settings.Setting.path(obj, *args, **kwargs) coalib.settings.Setting.path_list(obj, *args, **kwargs) coalib.settings.Setting.typed_dict(key_type, value_type, default) Creates a function that converts a setting into a dict with the given types. Parameters • key_type – The type conversion function for the keys. • value_type – The type conversion function for the values. • default – The default value to use if no one is given by the user. Returns A conversion function. coalib.settings.Setting.typed_list(conversion_func) Creates a function that converts a setting into a list of elements each converted with the given conversion func- tion. Parameters conversion_func – The conversion function that converts a string into your desired list item object. Returns A conversion function. coalib.settings.Setting.typed_ordered_dict(key_type, value_type, default) Creates a function that converts a setting into an ordered dict with the given types. Parameters • key_type – The type conversion function for the keys. • value_type – The type conversion function for the values. • default – The default value to use if no one is given by the user. Returns A conversion function. coalib.settings.Setting.url(obj, *args, **kwargs)
Module contents
22.1.2 Submodules
22.1.3 coalib.coala module coalib.coala.main()
22.1.4 coalib.coala_ci module coalib.coala_ci.main()
22.1.5 coalib.coala_dbus module coalib.coala_dbus.main() coalib.coala_dbus.on_disconnected() coalib.coala_dbus.sys_clean_exit()
22.1. coalib package 133 coala Documentation, Release 0.5.2
22.1.6 coalib.coala_delete_orig module
coalib.coala_delete_orig.main(log_printer=None, section: coalib.settings.Section.Section=None)
22.1.7 coalib.coala_format module
coalib.coala_format.main()
22.1.8 coalib.coala_json module
coalib.coala_json.main()
22.1.9 coalib.coala_main module
coalib.coala_main.do_nothing(*args) coalib.coala_main.run_coala(log_printer=None, print_results=
22.1.10 Module contents coalib.assert_supported_version()
.o88Oo._ d8P .ooOO8bo._ 88 '*Y8bo. __ YA '*Y8b __ ,dPYb, YA 68o68**8Oo. IP'`Yb "8D *"' "Y8o I8 8I Y8 'YB .8D
134 Chapter 22. coalib coala Documentation, Release 0.5.2
I8 8P '8 d8' 8D I8 8' 8 d8888b d AY ,gggo, ,ggggo, ,gggo,gg I8 dP ,gggo,gg Y, d888888 d' _.oP" dP" "Yb dP" "Y8go*8P" "Y8I I8dP dP" "Y8I q. Y8888P' d8 i8' i8' ,8P i8' ,8I I8P i8' ,8I "q. `Y88P' d8" ,d8,_ _,d8, ,d8' d8, ,d8b,,d8b,_ ,d8, ,d8b, Y ,o8P ooP""Y8888PP*"Y8888P" "Y8888P"`Y88P'"Y88P"Y8888P"`Y8 oooo888P"
22.1. coalib package 135 coala Documentation, Release 0.5.2
136 Chapter 22. coalib CHAPTER 23
What is coala?
coala is a simple COde AnaLysis Application. Its goal is to make static code analysis easy while remaining completely modular and therefore extendable and language independent. coala is written with a lower case “c”. Code analysis happens in python scripts while coala manages these, tries to provide helpful libraries and provides multiple user interfaces. (Currently we support only Console output but others will follow.) One could say coala unites all language independent parts of a linter and is arbitrarily extensible. To get started, take a look at our Installation Instructions and the Tutorial.
137 coala Documentation, Release 0.5.2
138 Chapter 23. What is coala? CHAPTER 24
What do I get?
24.1 As a User coala allows you to simply check your code against certain quality requirements. The checking routines are named Bears in coala. You can easily define a simple project file to check your project with all bears either shipped with coala or ones you found in the internet and trust.
24.2 As a Developer
If you are not satisfied with the functionality given by the bears we provide, you can easily write own bears. coala is written with easiness of extension in mind. That means: no big boilerplate, just write one small object with one routine, add the parameters you like and see how coala automates the organization of settings, user interaction and execution parallelization. You shouldn’t need to care about anything else than just writing your algorithm! See Writing Bears for more information on this. Also, coala provides an external API using the dbus message protocol. This allows other applications to easily use the code analysis functionalities coala provides in their applications. See External APIs for more information.
139 coala Documentation, Release 0.5.2
140 Chapter 24. What do I get? CHAPTER 25
Status and Stability of the Project
We are currently working hard to make this project reality. coala is currently usable, in beta stage and already provides more features than most language dependent alternatives. Every single commit is fully reviewed and checked with various automated methods including our testsuite covering all braches. Our master branch is continuously prereleased to our users so you can rely on the upcoming release being rock stable. If you want to see how the development progresses, check out https://github.com/coala-analyzer/coala
141 coala Documentation, Release 0.5.2
142 Chapter 25. Status and Stability of the Project CHAPTER 26
Indices and tables
• genindex • modindex • search
143 coala Documentation, Release 0.5.2
144 Chapter 26. Indices and tables Python Module Index
c coalib.misc.BuildManPage, 87 coalib, 134 coalib.misc.Constants, 88 coalib.bearlib, 82 coalib.misc.ContextManagers, 88 coalib.bearlib.abstractions, 80 coalib.misc.Decorators, 89 coalib.bearlib.abstractions.Lint, 77 coalib.misc.DictUtilities, 90 coalib.bearlib.abstractions.SectionCreatablecoalib.misc.Enum, , 91 79 coalib.misc.Exceptions, 91 coalib.bearlib.languages, 82 coalib.misc.MutableValue, 91 coalib.bearlib.languages.definitions, coalib.misc.Shell, 91 80 coalib.misc.StringConverter, 92 coalib.bearlib.languages.documentation, coalib.output, 104 82 coalib.output.ConfWriter, 98 coalib.bearlib.languages.documentation.DocstyleDefinitioncoalib.output.ConsoleInteraction, , 98 80 coalib.output.dbus, 96 coalib.bearlib.languages.documentation.DocumentationCommentcoalib.output.dbus.BuildDbusService, , 93 81 coalib.output.dbus.DbusApp, 93 coalib.bearlib.languages.documentation.DocumentationExtractioncoalib.output.dbus.DbusDocument, , 94 81 coalib.output.dbus.DbusServer, 94 coalib.bearlib.languages.LanguageDefinitioncoalib.output.Interactions, , 103 82 coalib.output.JSONEncoder, 103 coalib.bearlib.spacing, 82 coalib.output.printers, 98 coalib.bearlib.spacing.SpacingHelper, coalib.output.printers.EspeakPrinter, 82 96 coalib.bears, 85 coalib.output.printers.HTMLWriter, 96 coalib.bears.Bear, 83 coalib.output.printers.ListLogPrinter, coalib.bears.BEAR_KIND, 83 97 coalib.bears.GlobalBear, 84 coalib.output.printers.LOG_LEVEL, 97 coalib.bears.LocalBear, 84 coalib.output.printers.LogPrinter, 97 coalib.coala, 133 coalib.output.printers.StringPrinter, coalib.coala_ci, 133 98 coalib.coala_dbus, 133 coalib.output.Tagging, 103 coalib.coala_delete_orig, 134 coalib.parsing, 112 coalib.coala_format, 134 coalib.parsing.CliParsing, 109 coalib.coala_json, 134 coalib.parsing.ConfParser, 110 coalib.coala_main, 134 coalib.parsing.DefaultArgParser, 111 coalib.collecting, 87 coalib.parsing.Globbing, 111 coalib.collecting.Collectors, 85 coalib.parsing.LineParser, 112 coalib.collecting.Dependencies, 86 coalib.parsing.StringProcessing, 109 coalib.collecting.Importers, 86 coalib.parsing.StringProcessing.Core, coalib.misc, 92 104
145 coala Documentation, Release 0.5.2
coalib.parsing.StringProcessing.Filters, 108 coalib.parsing.StringProcessing.InBetweenMatch, 108 coalib.parsing.StringProcessing.Match, 109 coalib.processes, 121 coalib.processes.BearRunning, 113 coalib.processes.communication, 113 coalib.processes.communication.LogMessage, 113 coalib.processes.CONTROL_ELEMENT, 117 coalib.processes.LogPrinterThread, 117 coalib.processes.Processing, 118 coalib.results, 128 coalib.results.Diff, 123 coalib.results.HiddenResult, 124 coalib.results.LineDiff, 124 coalib.results.Result, 124 coalib.results.result_actions, 123 coalib.results.result_actions.ApplyPatchAction, 121 coalib.results.result_actions.OpenEditorAction, 121 coalib.results.result_actions.PrintDebugMessageAction, 122 coalib.results.result_actions.ResultAction, 122 coalib.results.result_actions.ShowPatchAction, 122 coalib.results.RESULT_SEVERITY, 124 coalib.results.ResultFilter, 125 coalib.results.SourcePosition, 126 coalib.results.SourceRange, 126 coalib.results.TextPosition, 127 coalib.results.TextRange, 127 coalib.settings, 133 coalib.settings.ConfigurationGathering, 128 coalib.settings.DocumentationComment, 130 coalib.settings.FunctionMetadata, 130 coalib.settings.Section, 131 coalib.settings.SectionFilling, 132 coalib.settings.Setting, 132
146 Python Module Index Index
A autoapply_actions() (in module acquire_actions_and_apply() (in module coalib.processes.Processing), 118 coalib.output.ConsoleInteraction), 98 acquire_settings() (in module B coalib.output.ConsoleInteraction), 98 basics_match() (in module coalib.results.ResultFilter), add_after (coalib.results.LineDiff.LineDiff attribute), 124 125 add_lines() (coalib.results.Diff.Diff method), 123 Bear (class in coalib.bears.Bear), 83 add_or_create_setting() (coalib.settings.Section.Section bear_dirs() (coalib.settings.Section.Section method), 131 method), 131 begin (coalib.parsing.StringProcessing.InBetweenMatch.InBetweenMatch add_pair_to_dict() (in module coalib.misc.DictUtilities), attribute), 108 90 BuildDbusService (class in affected_code() (coalib.results.Diff.Diff method), 123 coalib.output.dbus.BuildDbusService), 93 Analyze() (coalib.output.dbus.DbusDocument.DbusDocumentBuildManPage (class in coalib.misc.BuildManPage), 87 method), 94 append() (coalib.settings.Section.Section method), 131 C append_to_sections() (in module coalib.settings.Section), change (coalib.results.LineDiff.LineDiff attribute), 124 131 change_line() (coalib.results.Diff.Diff method), 123 apply() (coalib.results.Result.Result method), 124 check_conflicts() (in module coalib.parsing.CliParsing), apply() (coalib.results.result_actions.ApplyPatchAction.ApplyPatchAction109 method), 121 check_prerequisites() (coalib.bearlib.abstractions.Lint.Lint apply() (coalib.results.result_actions.OpenEditorAction.OpenEditorActionclass method), 78 method), 121 check_prerequisites() (coalib.bears.Bear.Bear class apply() (coalib.results.result_actions.PrintDebugMessageAction.PrintDebugMessageActionmethod), 83 method), 122 check_result_ignore() (in module apply() (coalib.results.result_actions.ResultAction.ResultAction coalib.processes.Processing), 118 method), 122 choose_action() (in module apply() (coalib.results.result_actions.ShowPatchAction.ShowPatchActioncoalib.output.ConsoleInteraction), 99 method), 122 CircularDependencyError, 86 apply_from_section() (coalib.results.result_actions.ResultAction.ResultActionclear() (coalib.output.printers.StringPrinter.StringPrinter method), 122 method), 98 ApplyPatchAction (class in close_tag() (coalib.output.printers.HTMLWriter.HTMLWriter coalib.results.result_actions.ApplyPatchAction), method), 96 121 coalib (module), 134 arguments (coalib.bearlib.abstractions.Lint.Lint at- coalib.bearlib (module), 82 tribute), 78 coalib.bearlib.abstractions (module), 80 arguments_to_lists() (in module coalib.misc.Decorators), coalib.bearlib.abstractions.Lint (module), 77 89 coalib.bearlib.abstractions.SectionCreatable (module), 79 ask_for_action_and_apply() (in module coalib.bearlib.languages (module), 82 coalib.output.ConsoleInteraction), 99 coalib.bearlib.languages.definitions (module), 80 assert_supported_version() (in module coalib), 134 coalib.bearlib.languages.documentation (module), 82
147 coala Documentation, Release 0.5.2 coalib.bearlib.languages.documentation.DocstyleDefinition coalib.output.Tagging (module), 103 (module), 80 coalib.parsing (module), 112 coalib.bearlib.languages.documentation.DocumentationCommentcoalib.parsing.CliParsing (module), 109 (module), 81 coalib.parsing.ConfParser (module), 110 coalib.bearlib.languages.documentation.DocumentationExtractioncoalib.parsing.DefaultArgParser (module), 111 (module), 81 coalib.parsing.Globbing (module), 111 coalib.bearlib.languages.LanguageDefinition (module), coalib.parsing.LineParser (module), 112 82 coalib.parsing.StringProcessing (module), 109 coalib.bearlib.spacing (module), 82 coalib.parsing.StringProcessing.Core (module), 104 coalib.bearlib.spacing.SpacingHelper (module), 82 coalib.parsing.StringProcessing.Filters (module), 108 coalib.bears (module), 85 coalib.parsing.StringProcessing.InBetweenMatch (mod- coalib.bears.Bear (module), 83 ule), 108 coalib.bears.BEAR_KIND (module), 83 coalib.parsing.StringProcessing.Match (module), 109 coalib.bears.GlobalBear (module), 84 coalib.processes (module), 121 coalib.bears.LocalBear (module), 84 coalib.processes.BearRunning (module), 113 coalib.coala (module), 133 coalib.processes.communication (module), 113 coalib.coala_ci (module), 133 coalib.processes.communication.LogMessage (module), coalib.coala_dbus (module), 133 113 coalib.coala_delete_orig (module), 134 coalib.processes.CONTROL_ELEMENT (module), 117 coalib.coala_format (module), 134 coalib.processes.LogPrinterThread (module), 117 coalib.coala_json (module), 134 coalib.processes.Processing (module), 118 coalib.coala_main (module), 134 coalib.results (module), 128 coalib.collecting (module), 87 coalib.results.Diff (module), 123 coalib.collecting.Collectors (module), 85 coalib.results.HiddenResult (module), 124 coalib.collecting.Dependencies (module), 86 coalib.results.LineDiff (module), 124 coalib.collecting.Importers (module), 86 coalib.results.Result (module), 124 coalib.misc (module), 92 coalib.results.result_actions (module), 123 coalib.misc.BuildManPage (module), 87 coalib.results.result_actions.ApplyPatchAction (module), coalib.misc.Constants (module), 88 121 coalib.misc.ContextManagers (module), 88 coalib.results.result_actions.OpenEditorAction (module), coalib.misc.Decorators (module), 89 121 coalib.misc.DictUtilities (module), 90 coalib.results.result_actions.PrintDebugMessageAction coalib.misc.Enum (module), 91 (module), 122 coalib.misc.Exceptions (module), 91 coalib.results.result_actions.ResultAction (module), 122 coalib.misc.MutableValue (module), 91 coalib.results.result_actions.ShowPatchAction (module), coalib.misc.Shell (module), 91 122 coalib.misc.StringConverter (module), 92 coalib.results.RESULT_SEVERITY (module), 124 coalib.output (module), 104 coalib.results.ResultFilter (module), 125 coalib.output.ConfWriter (module), 98 coalib.results.SourcePosition (module), 126 coalib.output.ConsoleInteraction (module), 98 coalib.results.SourceRange (module), 126 coalib.output.dbus (module), 96 coalib.results.TextPosition (module), 127 coalib.output.dbus.BuildDbusService (module), 93 coalib.results.TextRange (module), 127 coalib.output.dbus.DbusApp (module), 93 coalib.settings (module), 133 coalib.output.dbus.DbusDocument (module), 94 coalib.settings.ConfigurationGathering (module), 128 coalib.output.dbus.DbusServer (module), 94 coalib.settings.DocumentationComment (module), 130 coalib.output.Interactions (module), 103 coalib.settings.FunctionMetadata (module), 130 coalib.output.JSONEncoder (module), 103 coalib.settings.Section (module), 131 coalib.output.printers (module), 98 coalib.settings.SectionFilling (module), 132 coalib.output.printers.EspeakPrinter (module), 96 coalib.settings.Setting (module), 132 coalib.output.printers.HTMLWriter (module), 96 collect_all_bears_from_sections() (in module coalib.output.printers.ListLogPrinter (module), 97 coalib.collecting.Collectors), 85 coalib.output.printers.LOG_LEVEL (module), 97 collect_bears() (in module coalib.collecting.Collectors), coalib.output.printers.LogPrinter (module), 97 85 coalib.output.printers.StringPrinter (module), 98 collect_dirs() (in module coalib.collecting.Collectors), 85
148 Index coala Documentation, Release 0.5.2 collect_files() (in module coalib.collecting.Collectors), 85 dispose_document() (coalib.output.dbus.DbusServer.DbusServer collect_registered_bears_dirs() (in module method), 95 coalib.collecting.Collectors), 86 DisposeDocument() (coalib.output.dbus.DbusServer.DbusServer column (coalib.results.TextPosition.TextPosition at- method), 94 tribute), 127 do_nothing() (in module coalib.coala_main), 134 config_file() (coalib.bearlib.abstractions.Lint.Lint static docstyle (coalib.bearlib.languages.documentation.DocstyleDefinition.DocstyleDefinition method), 78 attribute), 80 ConflictError, 124 DocstyleDefinition (class in ConfParser (class in coalib.parsing.ConfParser), 110 coalib.bearlib.languages.documentation.DocstyleDefinition), ConfWriter (class in coalib.output.ConfWriter), 98 80 copy() (coalib.settings.Section.Section method), 131 DocumentationComment (class in create_app() (coalib.output.dbus.DbusServer.DbusServer coalib.bearlib.languages.documentation.DocumentationComment), method), 95 81 create_document() (coalib.output.dbus.DbusApp.DbusApp DocumentationComment (class in method), 93 coalib.settings.DocumentationComment), create_document() (coalib.output.dbus.DbusServer.DbusServer 130 method), 95 create_json_encoder() (in module E coalib.output.JSONEncoder), 103 end (coalib.parsing.StringProcessing.InBetweenMatch.InBetweenMatch create_params_from_section() attribute), 108 (coalib.settings.FunctionMetadata.FunctionMetadataend (coalib.results.TextRange.TextRange attribute), 127 method), 130 end_position (coalib.parsing.StringProcessing.Match.Match create_process_group() (in module attribute), 109 coalib.processes.Processing), 118 enforce_signature() (in module coalib.misc.Decorators), CreateDocument() (coalib.output.dbus.DbusServer.DbusServer 89 method), 94 enum() (in module coalib.misc.Enum), 91 err() (coalib.output.printers.LogPrinter.LogPrinter D method), 97 DbusApp (class in coalib.output.dbus.DbusApp), 93 escape() (in module coalib.parsing.StringProcessing.Core), DbusDocument (class in 104 coalib.output.dbus.DbusDocument), 94 escape_path_argument() (in module coalib.misc.Shell), DbusServer (class in coalib.output.dbus.DbusServer), 94 91 debug() (coalib.output.printers.LogPrinter.LogPrinter EspeakPrinter (class in method), 97 coalib.output.printers.EspeakPrinter), 96 default_arg_parser() (in module executable (coalib.bearlib.abstractions.Lint.Lint at- coalib.parsing.DefaultArgParser), 111 tribute), 78 DEFAULT_TAB_WIDTH execute() (coalib.bears.Bear.Bear method), 83 (coalib.bearlib.spacing.SpacingHelper.SpacingHelperexecute_section() (in module attribute), 82 coalib.processes.Processing), 118 delete (coalib.results.LineDiff.LineDiff attribute), 124 expand() (coalib.results.SourceRange.SourceRange delete_line() (coalib.results.Diff.Diff method), 123 method), 126 delete_setting() (coalib.settings.Section.Section method), expand() (coalib.results.TextRange.TextRange method), 131 127 delete_tagged_results() (in module extract_documentation() (in module coalib.output.Tagging), 103 coalib.bearlib.languages.documentation.DocumentationExtraction), Diff (class in coalib.results.Diff), 123 81 diff_message (coalib.bearlib.abstractions.Lint.Lint extract_documentation_with_markers() (in module attribute), 78 coalib.bearlib.languages.documentation.DocumentationExtraction), diff_severity (coalib.bearlib.abstractions.Lint.Lint at- 81 tribute), 78 dispose_app() (coalib.output.dbus.DbusServer.DbusServer F method), 95 fail_acquire_settings() (in module dispose_document() (coalib.output.dbus.DbusApp.DbusApp coalib.output.Interactions), 103 method), 93
Index 149 coala Documentation, Release 0.5.2
file (coalib.results.SourcePosition.SourcePosition at- G tribute), 126 gather_configuration() (in module file (coalib.results.SourceRange.SourceRange attribute), coalib.settings.ConfigurationGathering), 126 128 fill_queue() (in module coalib.processes.Processing), 119 generate_config_file() (coalib.bearlib.abstractions.Lint.Lint fill_section() (in module coalib.settings.SectionFilling), method), 78 132 generate_eq() (in module coalib.misc.Decorators), 89 fill_settings() (in module coalib.settings.SectionFilling), generate_ordering() (in module coalib.misc.Decorators), 132 89 filter_raising_callables() (in module generate_repr() (in module coalib.misc.Decorators), 90 coalib.processes.Processing), 119 get() (coalib.settings.Section.Section method), 131 filter_results() (in module coalib.results.ResultFilter), 125 get_action_info() (in module finalize_options() (coalib.misc.BuildManPage.BuildManPage coalib.output.ConsoleInteraction), 99 method), 87 get_config_dir() (coalib.bears.Bear.Bear method), 83 finalize_options() (coalib.output.dbus.BuildDbusService.BuildDbusServiceget_config_directory() (in module method), 93 coalib.settings.ConfigurationGathering), find_user_config() (in module 129 coalib.settings.ConfigurationGathering), get_cpu_count() (in module coalib.processes.Processing), 128 119 FindConfigFile() (coalib.output.dbus.DbusDocument.DbusDocumentget_default_actions() (in module method), 94 coalib.processes.Processing), 119 fnmatch() (in module coalib.parsing.Globbing), 111 get_dependencies() (coalib.bears.Bear.Bear static for_bears() (coalib.collecting.Dependencies.CircularDependencyErrormethod), 83 class method), 86 get_exitcode() (in module coalib.misc.Exceptions), 91 format_line() (in module get_file_dict() (in module coalib.processes.Processing), coalib.results.result_actions.ShowPatchAction), 119 123 get_global_dependency_results() (in module format_lines() (in module coalib.processes.BearRunning), 113 coalib.output.ConsoleInteraction), 99 get_ignore_scope() (in module format_man_page() (coalib.misc.BuildManPage.ManPageFormatter coalib.processes.Processing), 119 method), 88 get_indentation() (coalib.bearlib.spacing.SpacingHelper.SpacingHelper from_clang_fixit() (coalib.results.Diff.Diff class method), method), 82 123 get_local_dependency_results() (in module from_clang_range() (coalib.results.SourceRange.SourceRange coalib.processes.BearRunning), 113 class method), 126 get_metadata() (coalib.bearlib.abstractions.SectionCreatable.SectionCreatable from_docstring() (coalib.settings.DocumentationComment.DocumentationCommentclass method), 79 class method), 130 get_metadata() (coalib.bears.Bear.Bear class method), 83 from_function() (coalib.settings.FunctionMetadata.FunctionMetadataget_metadata() (coalib.bears.LocalBear.LocalBear class class method), 130 method), 84 from_section() (coalib.bearlib.abstractions.SectionCreatable.SectionCreatableget_metadata() (coalib.results.result_actions.ResultAction.ResultAction class method), 79 class method), 122 from_string_arrays() (coalib.results.Diff.Diff class get_next_global_bear() (in module method), 123 coalib.processes.BearRunning), 113 from_values() (coalib.parsing.StringProcessing.InBetweenMatch.InBetweenMatchget_non_optional_settings() class method), 108 (coalib.bearlib.abstractions.SectionCreatable.SectionCreatable from_values() (coalib.results.Result.Result class method), class method), 79 125 get_non_optional_settings() (coalib.bears.Bear.Bear class from_values() (coalib.results.SourceRange.SourceRange method), 83 class method), 126 get_optional_settings() (coalib.bearlib.abstractions.SectionCreatable.SectionCreatable from_values() (coalib.results.TextRange.TextRange class class method), 79 method), 127 get_or_create_app() (coalib.output.dbus.DbusServer.DbusServer FunctionMetadata (class in method), 95 coalib.settings.FunctionMetadata), 130 get_or_create_document() (coalib.output.dbus.DbusServer.DbusServer
150 Index coala Documentation, Release 0.5.2
method), 95 is_applicable() (coalib.results.result_actions.PrintDebugMessageAction.PrintDebugMessageAction get_public_members() (in module static method), 122 coalib.misc.Decorators), 90 is_applicable() (coalib.results.result_actions.ResultAction.ResultAction get_running_processes() (in module static method), 122 coalib.processes.Processing), 119 is_applicable() (coalib.results.result_actions.ShowPatchAction.ShowPatchAction get_section() (coalib.parsing.ConfParser.ConfParser static method), 122 method), 110 is_comment() (coalib.output.ConfWriter.ConfWriter get_shell_type() (in module coalib.misc.Shell), 91 static method), 98 get_tag_path() (in module coalib.output.Tagging), 104 is_enabled() (coalib.settings.Section.Section method), get_tags_dir() (in module coalib.output.Tagging), 104 131 GetConfigFile() (coalib.output.dbus.DbusDocument.DbusDocument method), 94 J gives_corrected (coalib.bearlib.abstractions.Lint.Lint at- join() (coalib.results.TextRange.TextRange class tribute), 78 method), 127 glob() (in module coalib.parsing.Globbing), 111 GlobalBear (class in coalib.bears.GlobalBear), 84 K key (coalib.settings.Setting.Setting attribute), 132 H keys() (coalib.misc.StringConverter.StringConverter has_wildcard() (in module coalib.parsing.Globbing), 111 method), 92 HiddenResult (class in coalib.results.HiddenResult), 124 kind() (coalib.bears.Bear.Bear static method), 83 HTMLWriter (class in kind() (coalib.bears.GlobalBear.GlobalBear static coalib.output.printers.HTMLWriter), 96 method), 84 kind() (coalib.bears.LocalBear.LocalBear static method), I 84 iglob() (in module coalib.parsing.Globbing), 111 iimport_objects() (in module coalib.collecting.Importers), L 86 language (coalib.bearlib.languages.documentation.DocstyleDefinition.DocstyleDefinition import_objects() (in module coalib.collecting.Importers), attribute), 80 86 LanguageDefinition (class in InBetweenMatch (class in coalib.bearlib.languages.LanguageDefinition), coalib.parsing.StringProcessing.InBetweenMatch), 82 108 limit() (in module coalib.parsing.StringProcessing.Filters), info() (coalib.output.printers.LogPrinter.LogPrinter 108 method), 97 line (coalib.results.TextPosition.TextPosition attribute), initialize_options() (coalib.misc.BuildManPage.BuildManPage 127 method), 87 LineDiff (class in coalib.results.LineDiff), 124 initialize_options() (coalib.output.dbus.BuildDbusService.BuildDbusServiceLineParser (class in coalib.parsing.LineParser), 112 method), 93 Lint (class in coalib.bearlib.abstractions.Lint), 77 inside (coalib.parsing.StringProcessing.InBetweenMatch.InBetweenMatchlint() (coalib.bearlib.abstractions.Lint.Lint method), 78 attribute), 109 ListLogPrinter (class in instantiate_bears() (in module coalib.output.printers.ListLogPrinter), 97 coalib.processes.Processing), 119 load() (coalib.bearlib.languages.documentation.DocstyleDefinition.DocstyleDefinition instantiate_processes() (in module class method), 80 coalib.processes.Processing), 120 load_config_file() (in module interface (coalib.output.dbus.DbusDocument.DbusDocument coalib.settings.ConfigurationGathering), attribute), 94 129 interface (coalib.output.dbus.DbusServer.DbusServer at- load_configuration() (in module tribute), 95 coalib.settings.ConfigurationGathering), inverse_dicts() (in module coalib.misc.DictUtilities), 90 129 is_applicable() (coalib.results.result_actions.ApplyPatchAction.ApplyPatchActionload_tagged_results() (in module coalib.output.Tagging), static method), 121 104 is_applicable() (coalib.results.result_actions.OpenEditorAction.OpenEditorActionLocalBear (class in coalib.bears.LocalBear), 84 static method), 121 location_repr() (coalib.results.Result.Result method), 125
Index 151 coala Documentation, Release 0.5.2 log() (coalib.output.printers.LogPrinter.LogPrinter open_tag() (coalib.output.printers.HTMLWriter.HTMLWriter method), 97 method), 96 log_exception() (coalib.output.printers.LogPrinter.LogPrinterOpenEditorAction (class in method), 97 coalib.results.result_actions.OpenEditorAction), log_message() (coalib.bears.Bear.Bear method), 84 121 log_message() (coalib.output.printers.ListLogPrinter.ListLogPrinteroptional_params (coalib.settings.FunctionMetadata.FunctionMetadata method), 97 attribute), 130 log_message() (coalib.output.printers.LogPrinter.LogPrinteroriginal (coalib.results.Diff.Diff attribute), 124 method), 97 output_regex (coalib.bearlib.abstractions.Lint.Lint LogMessage (class in attribute), 78 coalib.processes.communication.LogMessage), overlaps() (coalib.results.Result.Result method), 125 113 overlaps() (coalib.results.TextRange.TextRange method), LogPrinter (class in coalib.output.printers.LogPrinter), 97 127 LogPrinterThread (class in coalib.processes.LogPrinterThread), 117 P parse() (coalib.parsing.ConfParser.ConfParser method), M 110 main() (in module coalib.coala), 133 parse() (coalib.parsing.LineParser.LineParser method), main() (in module coalib.coala_ci), 133 112 main() (in module coalib.coala_dbus), 133 parse_cli() (in module coalib.parsing.CliParsing), 109 main() (in module coalib.coala_delete_orig), 134 parse_custom_settings() (in module main() (in module coalib.coala_format), 134 coalib.parsing.CliParsing), 110 main() (in module coalib.coala_json), 134 path (coalib.output.dbus.DbusDocument.DbusDocument make_temp() (in module coalib.misc.ContextManagers), attribute), 94 88 path() (in module coalib.settings.Setting), 132 ManPageFormatter (class in coalib.misc.BuildManPage), path_list() (in module coalib.settings.Setting), 133 88 position (coalib.parsing.StringProcessing.Match.Match markers (coalib.bearlib.languages.documentation.DocstyleDefinition.DocstyleDefinitionattribute), 109 attribute), 80 position_is_escaped() (in module Match (class in coalib.parsing.StringProcessing.Match), coalib.parsing.StringProcessing.Core), 105 109 prepare_file() (in module coalib.misc.ContextManagers), match (coalib.parsing.StringProcessing.Match.Match at- 88 tribute), 109 prepare_string_argument() (in module coalib.misc.Shell), match_to_result() (coalib.bearlib.abstractions.Lint.Lint 91 method), 78 prerequisite_command (coalib.bearlib.abstractions.Lint.Lint merge_section_dicts() (in module attribute), 78 coalib.settings.ConfigurationGathering), prerequisite_fail_msg (coalib.bearlib.abstractions.Lint.Lint 129 attribute), 79 missing_dependencies() (coalib.bears.Bear.Bear class print_actions() (in module method), 84 coalib.output.ConsoleInteraction), 100 modified (coalib.results.Diff.Diff attribute), 124 print_affected_files() (in module MutableValue (class in coalib.misc.MutableValue), 91 coalib.output.ConsoleInteraction), 100 print_affected_lines() (in module N coalib.output.ConsoleInteraction), 100 nested_search_in_between() (in module print_bears() (in module coalib.parsing.StringProcessing.Core), 105 coalib.output.ConsoleInteraction), 100 non_optional_params (coalib.settings.FunctionMetadata.FunctionMetadataprint_beautified_diff() (in module attribute), 130 coalib.results.result_actions.ShowPatchAction), nothing_done() (in module 123 coalib.output.ConsoleInteraction), 100 print_lines() (in module coalib.output.ConsoleInteraction), 101 O print_result() (in module coalib.output.ConsoleInteraction), 101 on_disconnected() (in module coalib.coala_dbus), 133
152 Index coala Documentation, Release 0.5.2 print_result() (in module coalib.processes.Processing), results_to_dbus_struct() (coalib.output.dbus.DbusDocument.DbusDocument 120 static method), 94 print_results() (in module retrieve_stderr() (in module coalib.output.ConsoleInteraction), 101 coalib.misc.ContextManagers), 88 print_results_formatted() (in module retrieve_stdout() (in module coalib.output.ConsoleInteraction), 101 coalib.misc.ContextManagers), 88 print_results_no_input() (in module run() (coalib.bears.Bear.Bear method), 84 coalib.output.ConsoleInteraction), 101 run() (coalib.bears.GlobalBear.GlobalBear method), 84 print_section_beginning() (in module run() (coalib.bears.LocalBear.LocalBear method), 84 coalib.output.ConsoleInteraction), 102 run() (coalib.misc.BuildManPage.BuildManPage print_spaces_tabs_in_unicode() (in module method), 87 coalib.output.ConsoleInteraction), 102 run() (coalib.output.dbus.BuildDbusService.BuildDbusService PrintDebugMessageAction (class in method), 93 coalib.results.result_actions.PrintDebugMessageAction),run() (coalib.processes.LogPrinterThread.LogPrinterThread 122 method), 118 printer (coalib.output.printers.LogPrinter.LogPrinter at- run() (in module coalib.processes.BearRunning), 114 tribute), 97 run_bear() (in module coalib.processes.BearRunning), process_output() (coalib.bearlib.abstractions.Lint.Lint 114 method), 79 run_bear_from_section() (coalib.bears.Bear.Bear process_queues() (in module method), 84 coalib.processes.Processing), 120 run_coala() (in module coalib.coala_main), 134 run_global_bear() (in module R coalib.processes.BearRunning), 115 range (coalib.parsing.StringProcessing.Match.Match at- run_global_bears() (in module tribute), 109 coalib.processes.BearRunning), 115 range() (coalib.results.Diff.Diff method), 124 run_interactive_shell_command() (in module relative_flat_glob() (in module coalib.parsing.Globbing), coalib.misc.Shell), 91 111 run_local_bear() (in module relative_recursive_glob() (in module coalib.processes.BearRunning), 115 coalib.parsing.Globbing), 112 run_local_bears() (in module relative_wildcard_glob() (in module coalib.processes.BearRunning), 116 coalib.parsing.Globbing), 112 run_local_bears_on_file() (in module remove_range() (in module coalib.results.ResultFilter), coalib.processes.BearRunning), 116 125 run_shell_command() (in module coalib.misc.Shell), 92 remove_result_ranges_diffs() (in module coalib.results.ResultFilter), 125 S replace_spaces_with_tabs() save_sections() (in module (coalib.bearlib.spacing.SpacingHelper.SpacingHelper coalib.settings.ConfigurationGathering), method), 82 129 replace_stderr() (in module search_for() (in module coalib.misc.ContextManagers), 88 coalib.parsing.StringProcessing.Core), 105 replace_stdout() (in module search_in_between() (in module coalib.misc.ContextManagers), 88 coalib.parsing.StringProcessing.Core), 106 replace_tabs_with_spaces() Section (class in coalib.settings.Section), 131 (coalib.bearlib.spacing.SpacingHelper.SpacingHelperSectionCreatable (class in method), 82 coalib.bearlib.abstractions.SectionCreatable), require_setting() (in module 79 coalib.output.ConsoleInteraction), 102 send_msg() (in module coalib.processes.BearRunning), resolve() (in module coalib.collecting.Dependencies), 86 117 Result (class in coalib.results.Result), 124 SetConfigFile() (coalib.output.dbus.DbusDocument.DbusDocument ResultAction (class in method), 94 coalib.results.result_actions.ResultAction), Setting (class in coalib.settings.Setting), 132 122 severity_map (coalib.bearlib.abstractions.Lint.Lint attribute), 79
Index 153 coala Documentation, Release 0.5.2 show_bear() (in module to_string_dict() (coalib.processes.communication.LogMessage.LogMessage coalib.output.ConsoleInteraction), 102 method), 113 show_bears() (in module to_string_dict() (coalib.results.Result.Result method), coalib.output.ConsoleInteraction), 102 125 show_enumeration() (in module translate() (in module coalib.parsing.Globbing), 112 coalib.output.ConsoleInteraction), 103 trim_empty_matches() (in module ShowPatchAction (class in coalib.parsing.StringProcessing.Filters), 108 coalib.results.result_actions.ShowPatchAction), typed_dict() (in module coalib.settings.Setting), 133 122 typed_list() (in module coalib.settings.Setting), 133 simplify_section_result() (in module typed_ordered_dict() (in module coalib.settings.Setting), coalib.processes.Processing), 121 133 simulate_console_inputs() (in module coalib.misc.ContextManagers), 88 U source_ranges_match() (in module unescape() (in module coalib.results.ResultFilter), 126 coalib.parsing.StringProcessing.Core), 106 SourcePosition (class in coalib.results.SourcePosition), unescaped_rstrip() (in module 126 coalib.parsing.StringProcessing.Core), 106 SourceRange (class in coalib.results.SourceRange), 126 unescaped_search_for() (in module SpacingHelper (class in coalib.parsing.StringProcessing.Core), 106 coalib.bearlib.spacing.SpacingHelper), 82 unescaped_search_in_between() (in module split() (in module coalib.parsing.StringProcessing.Core), coalib.parsing.StringProcessing.Core), 107 106 unescaped_split() (in module split_diff() (coalib.results.Diff.Diff method), 124 coalib.parsing.StringProcessing.Core), 107 start (coalib.results.TextRange.TextRange attribute), 127 unescaped_strip() (in module str_nodesc (coalib.settings.FunctionMetadata.FunctionMetadata coalib.parsing.StringProcessing.Core), 108 attribute), 130 unified_diff (coalib.results.Diff.Diff attribute), 124 str_optional (coalib.settings.FunctionMetadata.FunctionMetadataupdate() (coalib.settings.Section.Section method), 131 attribute), 130 update_ordered_dict_key() (in module string (coalib.output.printers.StringPrinter.StringPrinter coalib.misc.DictUtilities), 91 attribute), 98 update_setting() (coalib.settings.Section.Section StringConverter (class in coalib.misc.StringConverter), 92 method), 131 StringPrinter (class in url() (in module coalib.settings.Setting), 133 coalib.output.printers.StringPrinter), 98 use_stderr (coalib.bearlib.abstractions.Lint.Lint attribute), subprocess_timeout() (in module 79 coalib.misc.ContextManagers), 89 use_stdin (coalib.bearlib.abstractions.Lint.Lint attribute), success_message (coalib.results.result_actions.ApplyPatchAction.ApplyPatchAction79 attribute), 121 user_options (coalib.misc.BuildManPage.BuildManPage success_message (coalib.results.result_actions.OpenEditorAction.OpenEditorActionattribute), 87 attribute), 122 user_options (coalib.output.dbus.BuildDbusService.BuildDbusService success_message (coalib.results.result_actions.ResultAction.ResultActionattribute), 93 attribute), 122 success_message (coalib.results.result_actions.ShowPatchAction.ShowPatchActionV attribute), 122 validate_results() (in module suppress_stdout() (in module coalib.processes.BearRunning), 117 coalib.misc.ContextManagers), 89 value (coalib.misc.StringConverter.StringConverter at- sys_clean_exit() (in module coalib.coala_dbus), 133 tribute), 92 T W tag_results() (in module coalib.output.Tagging), 104 warn() (coalib.output.printers.LogPrinter.LogPrinter task_done() (in module coalib.processes.BearRunning), method), 97 117 warn_nonexistent_targets() (in module TextPosition (class in coalib.results.TextPosition), 127 coalib.settings.ConfigurationGathering), TextRange (class in coalib.results.TextRange), 127 129
154 Index coala Documentation, Release 0.5.2 write() (coalib.output.printers.HTMLWriter.HTMLWriter method), 96 write_comment() (coalib.output.printers.HTMLWriter.HTMLWriter method), 96 write_section() (coalib.output.ConfWriter.ConfWriter method), 98 write_sections() (coalib.output.ConfWriter.ConfWriter method), 98 write_tag() (coalib.output.printers.HTMLWriter.HTMLWriter method), 96 Y yield_ignore_ranges() (in module coalib.processes.Processing), 121 yield_once() (in module coalib.misc.Decorators), 90 yield_tab_lengths() (coalib.bearlib.spacing.SpacingHelper.SpacingHelper method), 82
Index 155