Raincoat Documentation - Release 0.1.0 Joachim Jablon - Read the Docs

Page created by Ted Watkins
 
CONTINUE READING
Raincoat Documentation
             Release 0.1.0

           Joachim Jablon

                  Jan 25, 2018
Contents

1   Raincoat                                                                                                                                                                                                   3
    1.1 The problem . . . .        .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   3
    1.2 The solution . . . .       .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   4
    1.3 And beyond ! . . . .       .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   5
    1.4 Caveats and Gotchas        .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   5
    1.5 Todos . . . . . . . .      .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   6
    1.6 Acknowledgments .          .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   6

2   Installation                                                                                                                                                                                               7

3   Usage                                                                                                                                                                                                      9
    3.1 Command line tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .                                                                                              9
    3.2 Raincoat comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .                                                                                                9

4   Contributing                                                                                                                                                                                               11
    4.1 Types of Contributions .           .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   11
    4.2 Get Started! . . . . . . .         .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   12
    4.3 Pull Request Guidelines            .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   13
    4.4 Tips . . . . . . . . . . .         .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   13

5   Contributor Covenant Code of Conduct                                                                                                                                                                       15
    5.1 Our Pledge . . . . . . . . . . . . .                       .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   15
    5.2 Our Standards . . . . . . . . . . .                        .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   15
    5.3 Our Responsibilities . . . . . . . .                       .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   16
    5.4 Scope . . . . . . . . . . . . . . . .                      .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   16
    5.5 Enforcement . . . . . . . . . . . .                        .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   16
    5.6 Attribution . . . . . . . . . . . . .                      .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   16

6   Credits                                                                                                                                                                                                    17
    6.1 Development Lead . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .                                                                                               17
    6.2 Contributors (by alphabetic order) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .                                                                                             17

7   History                                                                                                                                                                                                    19
    7.1 0.8.6 (unreleased)     .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   19
    7.2 0.8.5 (2017-09-29)     .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   19
    7.3 0.8.3 (2017-07-09)     .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   19
    7.4 0.8.2 (2017-07-04)     .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   19

                                                                                                                                                                                                                i
7.5    0.8.1 (2017-07-04)   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   19
     7.6    0.8.0 (2017-04-18)   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   20
     7.7    0.7.0 (2017-04-01)   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   20
     7.8    0.6.0 (2017-02-22)   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   20
     7.9    0.5.0 (2016-11-06)   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   20
     7.10   0.4.3 (2016-11-06)   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   20
     7.11   0.4.1 (2016-11-06)   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   20
     7.12   0.4.0 (2016-10-16)   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   20
     7.13   0.3.0 (2016-10-15)   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   20

ii
Raincoat Documentation, Release 0.1.0

Contents:

Contents                                       1
Raincoat Documentation, Release 0.1.0

2                                       Contents
CHAPTER            1

                                                                                                         Raincoat

 Raincoat has you covered when you can’t stay DRY. When the time comes where you HAVE to copy code from a
third party, Raincoat will let you know when this code is changed so that you can update your local copy.

1.1 The problem

Lets say you’re using a lib named umbrella which provides a function named use_umbrella and it reads as such
:

def use_umbrella(umbrella):

     # Prepare umbrella
     umbrella.remove_pouch()
     umbrella.open()

     # Use umbrella
     while rain_detector.still_raining():
         umbrella.keep_over_me()

     # Put umbrella away
     umbrella.close()
     while not umbrella.is_wet():
         time.sleep(1)
     umbrella.put_pouch()

This function does what it says it does, but it’s not ideally splitted, depending on your needs. For example, maybe
at some point you realize you need each of the 3 separate parts to be a function of its own. Or maybe you can’t call
time.sleep in your app. Or do something else with the umbrella when it’s open like dance with it.
It’s also possible that you can’t really make a pull request because your needs are specific, or you don’t have the time
(that’s sad but, hey, I know it happens) or any other personnal reason. So what do you do ? There’s no real alternative.
You copy and paste the code, modify it to fit your needs and use your modified version. And whenever there’s a change
to the upstream function, chances are you’ll never know.

                                                                                                                      3
Raincoat Documentation, Release 0.1.0

1.2 The solution

Enter Raincoat.
You have made your own private copy of umbrella.use_umbrella (umbrella being at the time at version 14.5.7)
and it looks like this :

def dance_with_umbrella(umbrella):
        """
    I'm siiiiiinging in the rain !
    """
    # Prepare umbrella
    umbrella.remove_pouch()
    umbrella.open()

      # Use umbrella
      while rain_detector.still_raining():
          Dancer.sing_in_the_rain(umbrella)

      # Put umbrella away
      umbrella.close()
      while not umbrella.is_wet()
          time.sleep(1)
      umbrella.put_pouch()

Now simply add a comment somewhere (preferably just after the docstring) that says something like:

def dance_with_umbrella(umbrella):
     """
     I'm siiiiiinging in the rain !
     """
     # This code was adapted from the original umbrella.use_umbrella function
     # (we just changed the part inside the middle while loop)
     # Raincoat: pypi package: umbrella==14.5.7 path: umbrella/__init__.py element:
 ˓→use_umbrella

      ...

Now, if you run raincoat in your project (At this stage, I assume you’ve installed it with pip install
raincoat)

$ raincoat

It will:
    • Grep the code for all # Raincoat: comments and for each comment:
    • Look at the currently installed version of the lib (say, umbrella 16.0.3) (or, if not found, the latest version)
    • Compare with the version in the Raincoat comment (here, 14.5.7)
    • If they are different, download and pip install the specified version in a temp dir (using cached wheel as pip does
      by default, this should be quite fast in most cases)
    • Locate the code using the provided path for both the downloaded and the currently installed versions
    • Diff it
    • Tell you if there’s a difference (and mention the location of the original Raincoat comment)

4                                                                                                 Chapter 1. Raincoat
Raincoat Documentation, Release 0.1.0

Whether there is something to change or not, you’ve now verified your code with umbrella 16.0.3, so you can update
manually the umbrella comment.

# Raincoat: pypi package: umbrella==16.0.3 path: umbrella/__init__.py element: use_
 ˓→umbrella"

Raincoat can be used like a linter, you can integrate it in CI, make it a tox target. . .
Note that if you omit the last argument, Raincoat will analyze the whole module:

# Raincoat: pypi package: umbrella==16.0.3 path: umbrella/__init__.py

1.3 And beyond !

Actually, the base principle of Raincoat can be extended to many other subjects than PyPI packages. To fit this,
Raincoat was written with a modular achitecture allowing other kinds of Raincoat comments.
For now Raincoat comes with:
    • PyPI: The module presented above
    • Django: A module that checks if a given bug in Django for which you may have had to write a workaround is
      fixed in your (or the latest) version of Django. Syntax is :

# Raincoat: django ticket: #26976

    • PyGitHub : Same as the PyPI module but using Github. It’s useful if your upstream is a python package that’s
      not on PyPI, like, say, the Python Standard Library itself. Say you want to know if the element Maildir.
      _lookup in the file Lib/mailbox.py changed on the master branch since commit 43ba8861. What you
      can do is:

# Raincoat: pygithub repo: python/cpython@43ba8861 branch: master path: Lib/mailbox.
 ˓→py element: Maildir._lookup

Of course, feel free to code your own !

1.4 Caveats and Gotchas

    • The 2 elements you provide in path should be the location of the file when the package is installed (in most case,
      this should match the location of the file in the project repo) and the object defined in this file. This object can
      be a variable, a class, a function or a method.
    • Your own customized (copied/pasted) version of the function will not be analyzed. In fact, you don’t even have
      to place the Raincoat comment in the function that uses it.
    • You may realize that raincoat works best if you can use some kind of pip cache.
    • Raincoat does not run files (either your files or the package file). Package files are parsed and the AST is
      analyzed.
    • If for any reason, several code objects are identically named in the file you analyze, there’s no guarantee you’ll
      get any specific one.
    • The Django module uses the public GitHub API and does a few calls. This should not be a concern most
      of the time, but you may experience rate-limiting issues if Raincoat is launched from an IP that does a lot of
      calls to the GitHub API (e.g. Travis). In this case, from your Travis settings, set the environment variable

1.3. And beyond !                                                                                                       5
Raincoat Documentation, Release 0.1.0

      RAINCOAT_GITHUB_TOKEN to username:github_token, github_token being a token gener-
      ated here with all checkboxes unchecked.
    • So few people use Raincoat for now that you should expect a few bumps down the road. This being said, fire
      issues and pull requetes at will and I’ll do my best to answer them in a timely manner.

1.5 Todos

Things I’d like to add at some point
    • An option to update a comment automatically
    • A way to say you want your customized function to be diffed too (in case it’s a close copy and you want to keep
      track of what you’ve modified)
    • A way to access the original function without the process of downloading the whole package and installing it
      for nothing. We just want a single file of it.
    • A smart way to make raincoat not need a pip cache (a cache of its own, or something)

1.6 Acknowledgments

This code is open-sourced and maintained by me (Joachim Jablon) during both my free time and my time working at
PeopleDoc, based on an idea and a first implemention made at Smart Impulse. Kudos to these 2 companies.

6                                                                                            Chapter 1. Raincoat
CHAPTER   2

                        Installation

Install with

pip install raincoat

                                   7
Raincoat Documentation, Release 0.1.0

8                                       Chapter 2. Installation
CHAPTER           3

                                                                                                            Usage

3.1 Command line tool

Up to date usage information is accessible with the command line interface by using

raincoat --help

3.2 Raincoat comments

Raincoat will detect comments in your code, that look like this :

# Raincoat: pypi package: PACKAGE_NAME==VERSION path: PATH [element: OBJECT_NAME]

Where :
    • PACKAGE_NAME is the name you would use with pip
    • VERSION is required (note : it can be tempting to imagine that other oprators are available besides ==, it’s not
      the case)
    • PATH is the path between the place where pip would install a package (usually site-packages) and the file
      containing the definition you want to check. It starts with the top module name (which in some cases is different
      from the package name, I know, it’s frustrating.)
    • OBJECT_NAME is the name of either a function, a class or a method. For methods, the expected format is
      ClassName.method_name
    • If element is not specified, the whole module will be analyzed.

                                                                                                                     9
Raincoat Documentation, Release 0.1.0

10                                      Chapter 3. Usage
CHAPTER           4

                                                                                                 Contributing

Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.
Note that all contributions are subject to the Contributor Covenant Code of Conduct reproduced below.
You can contribute in many ways:

4.1 Types of Contributions

4.1.1 Report Bugs

Report bugs at https://github.com/peopledoc/raincoat/issues.
If you are reporting a bug, please include:
    • Your operating system name and version.
    • Any details about your local setup that might be helpful in troubleshooting.
    • Detailed steps to reproduce the bug.

4.1.2 Fix Bugs

Look through the GitHub issues for bugs. Anything tagged with “bug” is open to whoever wants to implement it.

4.1.3 Implement Features

Look through the GitHub issues for features. Anything tagged with “feature” is open to whoever wants to implement
it.

                                                                                                                  11
Raincoat Documentation, Release 0.1.0

4.1.4 Write Documentation

Raincoat could always use more documentation, whether as part of the official Raincoat docs, in docstrings, or even
on the web in blog posts, articles, and such.

4.1.5 Submit Feedback

The best way to send feedback is to file an issue at https://github.com/peopledoc/raincoat/issues.
If you are proposing a feature:
      • Explain in detail how it would work.
      • Keep the scope as narrow as possible, to make it easier to implement.
      • Remember that this is a volunteer-driven project, and that contributions are welcome :)

4.2 Get Started!

Ready to contribute? Here’s how to set up raincoat for local development.
     1. Fork the raincoat repo on GitHub.
     2. Clone your fork locally:

        $ git clone git@github.com:your_name_here/raincoat.git

     3. Install your local copy into a virtualenv. Assuming you have virtualenvwrapper installed, this is how you set up
        your fork for local development:

        $ mkvirtualenv raincoat
        $ cd raincoat/
        $ python setup.py develop

     4. Create a branch for local development:

        $ git checkout -b name-of-your-bugfix-or-feature

        Now you can make your changes locally.
     5. When you’re done making changes, check that your changes pass flake8 and the tests, including testing other
        Python versions with tox:

        $ flake8 django_readonly_field tests
        $ python setup.py test
        $ tox

        To get flake8 and tox, just pip install them into your virtualenv.
     6. Commit your changes and push your branch to GitHub:

        $ git add .
        $ git commit -m "Your detailed description of your changes."
        $ git push origin name-of-your-bugfix-or-feature

     7. Submit a pull request through the GitHub website.

12                                                                                         Chapter 4. Contributing
Raincoat Documentation, Release 0.1.0

4.3 Pull Request Guidelines

Before you submit a pull request, check that it meets these guidelines:
   1. The pull request should include tests.
   2. If the pull request adds functionality, the docs should be updated. Put your new functionality into a function
      with a docstring, and add the feature to the list in README.rst.
   3. The pull request should work for Python 2.6, 2.7, and 3.3, and for PyPy. Check https://travis-ci.org/peopledoc/
      raincoat/pull_requests and make sure that the tests pass for all supported Python versions.

4.4 Tips

To run a subset of tests:

$ python -m unittest tests.test_django_readonly_field

4.3. Pull Request Guidelines                                                                                      13
Raincoat Documentation, Release 0.1.0

14                                      Chapter 4. Contributing
CHAPTER            5

                                                         Contributor Covenant Code of Conduct

5.1 Our Pledge

In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making
participation in our project and our community a harassment-free experience for everyone, regardless of age, body
size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race,
religion, or sexual identity and orientation.

5.2 Our Standards

Examples of behavior that contributes to creating a positive environment include:
    • Using welcoming and inclusive language
    • Being respectful of differing viewpoints and experiences
    • Gracefully accepting constructive criticism
    • Focusing on what is best for the community
    • Showing empathy towards other community members
Examples of unacceptable behavior by participants include:
    • The use of sexualized language or imagery and unwelcome sexual attention or
advances * Trolling, insulting/derogatory comments, and personal or political attacks * Public or private harassment *
Publishing others’ private information, such as a physical or electronic
      address, without explicit permission
    • Other conduct which could reasonably be considered inappropriate in a professional setting

                                                                                                                      15
Raincoat Documentation, Release 0.1.0

5.3 Our Responsibilities

Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appro-
priate and fair corrective action in response to any instances of unacceptable behavior.
Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits,
issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any
contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.

5.4 Scope

This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the
project or its community. Examples of representing a project or community include using an official project e-mail
address, posting via an official social media account, or acting as an appointed representative at an online or offline
event. Representation of a project may be further defined and clarified by project maintainers.

5.5 Enforcement

Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team
(see AUTHORS file). All complaints will be reviewed and investigated and will result in a response that is deemed
necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard
to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent
repercussions as determined by other members of the project’s leadership.

5.6 Attribution

This Code of Conduct is adapted from the Contributor Covenant, version 1.4, available at http://contributor-covenant.
org/version/1/4/

16                                                       Chapter 5. Contributor Covenant Code of Conduct
CHAPTER   6

                                                                           Credits

6.1 Development Lead

  • Joachim Jablon / @ewjoachim 

6.2 Contributors (by alphabetic order)

                                                                                 17
Raincoat Documentation, Release 0.1.0

18                                      Chapter 6. Credits
CHAPTER   7

                                                                            History

7.1 0.8.6 (unreleased)

  • Nothing changed yet.

7.2 0.8.5 (2017-09-29)

  • Nothing changed yet

7.3 0.8.3 (2017-07-09)

  • Replace setup.py with setup.cfg
  • Lot of packaging work to make it simpler to test / lint / release

7.4 0.8.2 (2017-07-04)

  • Fixed error in release

7.5 0.8.1 (2017-07-04)

  • Fixed warning not appearing for invalid Raincoat comments

                                                                                  19
Raincoat Documentation, Release 0.1.0

7.6 0.8.0 (2017-04-18)

     • Added PyGitHub module to follow python sources on GitHub that are not PyPI packages

7.7 0.7.0 (2017-04-01)

     • Added colors to the output

7.8 0.6.0 (2017-02-22)

     • Refactored the code for easier testing
     • Added Django module to be informed when Django bugs are fixed

7.9 0.5.0 (2016-11-06)

     • Standardized the comments form to prepare for other types of Raincoat comments

7.10 0.4.3 (2016-11-06)

     • Included missing modules in the release

7.11 0.4.1 (2016-11-06)

     • Improved release process

7.12 0.4.0 (2016-10-16)

     • Fix reqs
     • Perfs improvements when analyzing huge codebases
     • Logic error when a files doesn’t end with a newline
     • Refactor the Match class into its own module with its own logic

7.13 0.3.0 (2016-10-15)

     • Initial release
     • Support for Python 2 and 3

20                                                                                       Chapter 7. History
You can also read