VSI Common

Linux	Windows	macOS	docs

In order to use these directories, all you have to do is

Linux (bash)
```
source env.bsh
```
Windows (batch)
```
call env.bat
```

Python

Preferred

pip install git+https://github.com/visionsystemsinc/vsi_common.git

Other options

git clone git@github.com:visionsystemsinc/vsi_common.git .

and one of

  pip install .
  python setup.py install

Developers of a module should install an editable version of the library in your python environment by cloning the repo and running one of

  python setup.py develop
  pip install -e .

What is this repository for?

Common tools we use at VSI for any project/effort where we can use this "VSI" asset

How do I get set up?

Summary of set up
Configuration
Dependencies
Database configuration
How to run tests
- To run all the unit tests for python
```
python -m unittest discover -s {vsi_python_dir}
```
Deployment instructions

Contribution guidelines

Adding files
- Python
- Add files in the python directory. If it's a new effort, try and add it to the vsi package. If it is a large library and you don't have time to convert everything now, you can add it to the python dir in its own directory, and add a .pth file for it. Do NOT add .py file in the main python dir
- Script
- Linux scripts (written in bash, python, etc..) That are to be CLI only (not a python library meant to be imported EVER) go in the linux directory
  - Start files with
```
#!/usr/bin/env bash
```
  or
```
#!/usr/bin/env python
```
- Windows scripts (batch mainly) go in the windows directory
  - Start files with
```
@echo off
```
  - If you have a python script you would like to use as a command line, make it a .bat file, and start it with
```
1>2# : ^
'''
@echo off
python %~f0 %*
exit /b
'''
```
  - This will start the python in your path, and pass the script and all arguments, as uncorrupted as possible in windows batch.
  - This can work for anything other than python.
  - Use pythonw instead for gui tasks.
  - For special characters (like |), you'll need to add an escape character (^|) just to run the command, and then 2^n more for every batch file. So to call this batch file, you'll need 3 carats (^^^|). To escape !, you'll need to create a setlocal ENABLEDELAYEDEXPANSION arond the python call itself (its the %* part that is important). Side effects are currently unknown for using setlocal in this way, so it is not the default yet...
```
setlocal ENABLEDELAYEDEXPANSION
python %~f0 %*
endlocal
```
- If a script belongs in both (somehow) put it in Windows, and a relative (../Windows/myscript) symlink in Linux

Writing tests

Python
Write tests for your modules using the unittest

Tests should be stored separately in files names "test_*.py"

import unittest
class MyTestClass(unittest.TestCase):
def test_something(self): #This function MUST start with "test_"
  doSomething();
  self.assertEqual('abc', 'a'+'bc')

Test classes can contain a setUp function and tearDown function to be called before and after testing starts

class MyTestClass(unittest.TestCase):
def setUp(self):
  self.blah = doSomethingInitialize()
def tearDown(self):
  cleanUpEverything(self.blah)
  self.blah = None

Code review
Other guidelines

Documentation

Documentation uses sphinx. To compile documentation, run

just docs
just docs view

Sphinx documentation can be embedded in any source file. There must be a #*# comment stating the filename and any # comments surrounded with #** will be added to sphinx documentation

# This documentation path will become:
#   {VSI_COMMON_DIR}/docs/example/readme.auto.rst
# Other files will refer to is the document with .auto. in the name
#*# example/readme.rst

# The following three lines are included

#**
# .. note::
#
#     You can not run the script and download in one call, you must call new_just as a file, not a pipe stream. ``
#**

# This line is not documentation
# No #** at the beginning of this line

Documentation FAQ

Why is there an bash:env directive, when envvar already exists?
- They are both for documenting environment variables, bash:env should be used for locally scoped variables, that only affect that one file, while envvar might affect many files.

Who do I talk to?

Repo owner or admin
Other community or team contact

VisionSystemsInc / vsi_common

readme