Metadata-Version: 2.1
Name: dsi-cocoa
Version: 0.4.7
Summary: Clinic Opinionated Codebase Oversight and Analysis
Author-email: Nick Ross <tspread@uchicago.edu>, Trevor Spreadbury <tspread@uchicago.edu>
Maintainer: Nick Ross, Trevor Spreadbury
Keywords: codebase analysis,uchicago dsi
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Description-Content-Type: text/markdown
Requires-Dist: GitPython
Requires-Dist: pyflakes
Requires-Dist: pylint
Requires-Dist: nbconvert
Requires-Dist: ipython
Requires-Dist: termcolor
Requires-Dist: black
Requires-Dist: requests

# Clinic Opinionated Codebase Oversight and Analysis

[![Cocoa Error Analysis](https://github.com/dsi-clinic/cocoa/actions/workflows/error.badges.yml/badge.svg)](https://github.com/dsi-clinic/cocoa/actions/workflows/error.badges.yml)


This repository was developed in order to generate automated reports on how well codebases adhere to the [coding standards](https://github.com/dsi-clinic/coding-standards) of the University of Chicago's DSI [Clinic course](https://datascience.uchicago.edu/education/data-science-clinic/).

The goals of this codebase is to provide a quick and easy way to review code and to alert contributors where their code may be failing.

## Installation

`pip install dsi-cocoa`

To install the package locally, run the following command from the root of the repository:
```bash
python3 -m pip install .
```

## cocoa

This package contains a module `evaluate_repo` which runs code testing libraries against a repository. There are multiple ways that we want to be able to run this repo:

1. We want to be able to clone `cocoa` and then use it as part of their process.
2. We want administrators to be able to give it a list of repos to generate reports on all repos.
3. (Eventually) We want it to be able to run as a github action _on the repo itself_.
4. (Eventually) We want to be able to have adminstrative repo that can run it on other repos.

### How to run

Via command line:

```bash
cocoa /path/to/repo
```

As a python script:

```bash
python3 src/cocoa/evaluate_repo.py /path/to/repo
```

As a Python module:

```python
from cocoa.evaluate_repo import evaluate_repo

evaluate_repo('/path/to/repo', False)
```

A few important notes:

1. Make sure to `git pull` _before_ running this code.
1. This will get branch information for all branches.
1. This will only run the analysis (`pyflakes` on python files) for the code _in the current branch_. So if you run this while your current branch is `main` it will run on `main`.

#### Options

If you want to turn on linting, add the argument "--lint":

```bash
cocoa /path/to/repo --lint
```

Results are truncated by default. To print all results, use the verbose option:

```bash
cocoa /path/to/repo --verbose
```

If files modified/created only after a certain date are to be evaluated then use the date option:

```bash
cocoa /path/to/repo --date "YYYY-MM-DD"
```

Note: Please add date string in "YYYY-MM-DD" format.

All options can be combined like so:

```bash
cocoa /path/to/repo --lint --verbose --date "YYYY-MM-DD"
```


### Checks

The code run multiple checks on each repo. For each check run there are three possibilities:

1. WARNING: Most likely this needs to be fixed.
1. INFO: Log information for additional context.
1. ERROR: A critical issue that needs to be addressed.

For each of the checks below we have denoted what the check generates.

- Branch Hygiene:
  - [WARNING] Branch names
  - [INFO] Commit information for live branches.
- File Hygiene:
  - [ERROR] Unnecessary and cache file (such as .DS_Store or pycache files)
- Notebook Files (\*.ipynb):
  - [ERROR] Cells per notebook < 10, lines per cell < 15 and 0 functions defined
  - [ERROR] Linting: PyLint, Black, Flake and iSort
- Python Files
  - [ERROR] All Code in Functions
  - [ERROR] All functions have docstrings
  - [ERROR] Code uses off-limit libraries (subprocess)
  - [ERROR] Linting: PyLint, Black, Flake and iSort

### Github actions

For each of the ERRORS and WARNINGS above there is an associated github action that can be run to create a badge which we put in a table at the top of each clinic repo.
