Replace everything with the more up-to-date stuff from our monorepo

Author: initialed85

.dockerignore

@@ -1,29 +1,3 @@
+*.iml
+.git
 .idea
-pkg
-bin
-out
-src/github.com
-*.pyc
-*__pycache__
-gosnmp_python.so
-_gosnmp_python.so
-gosnmp_python.py
-gosnmp_python/py2
-gosnmp_python/cffi
-gopy
-prebuilt
-.cache
-.pytest_cache
-.vscode
-main.go
-build/
-dist/
-gosnmp_python.egg-info/
-.DS_Store
-Makefile
-go.py
-build.py
-.python-version
-scratch.py
-.eggs
-*VirtualEnv*

.gitignore

@@ -1,135 +1,79 @@
-## gosnmp-python
+# gosnmp-python
 
-The purpose of this module is to provide a Python interface to the Golang [gosnmp](https://github.com/soniah/gosnmp) module.
+This library binds [our fork](https://github.com/ftpsolutions/gosnmp) of [gosnmp](https://github.com/gosnmp/gosnmp) for use in Python3
+using [gopy](https://github.com/go-python/gopy).
 
-It was made very easy with the help of the Golang [gopy](https://github.com/go-python/gopy) module.
+## Versions
 
-#### Versions
+All versions 1.0.0 and up support Python 3 only! If you need Python 2 support, check out the following:
 
-This version (0.91) is the last version to support Python 2; all versions after this have been subject to a refactor and support Python 3
-only.
+- [https://github.com/ftpsolutions/gosnmp-python/tree/v0.91](https://github.com/ftpsolutions/gosnmp-python/tree/v0.91)
+- https://pypi.org/project/gosnmp-python/0.91/
 
-#### Limitations
+## Concept
 
-* Python command needs to be prefixed with GODEBUG=cgocheck=0 (or have that in the environment)
-* I've not implemented walk (as I didn't need it for my use-case, I just use get_next with Python)
-* Seems to have some odd memory problems with PyPy (via CFFI); lots of locks and stuff to try and alleviate that
+In the early days `gopy` was fairly limited in it's ability to track object allocation across the border of Go and Python.
 
-#### Prerequisites
+As a result, our implementation is fairly naive- we only pass primitive types from Go to Python (nothing that comes by reference).
 
-* Go 1.13
-* Python 2.7+
-* pip
-* virtualenvwrapper
-* pkgconfig/pkg-config
+Session are managed entirely on the Go side and identified with an integer- here are a few function signatures to demonstrate:
 
-#### Installation (from PyPI)
+- `NewRPCSessionV2c(hostname string, port int, community string, timeout, retries int) uint64`
+- `RPCConnect(sessionID uint64) error`
+- `RPCGet(sessionID uint64, oid string) (string, error)`
+- `RPCClose(sessionID uint64) error`
 
-* ```python -m pip install gosnmp-python```
+The functions that return complex data do so in a special JSON-based format- at this point `gopy` does it's magic and those functions are
+made available to Python.
 
-#### Installation (for prod)
+We then have `RPCSession` abstraction on the Python side that pulls things together in a class for convenience (saving you need the to keep
+track of the identifiers and handling deserialisation).
 
-* ```python setup.py install```
+## Weird gotchas
 
-#### Making a python wheel install file (for distribution)
+We're building for Python3 and we use a `python-config` script for Python3 however we're using a `python.pc` file from Python2.
 
-* ```python setup.py bdist_wheel```
+I dunno why this has to be this way, but it's the only way I can get the C Python API GIL lock/unlock calls to be available to
+Go (`C.PyEval_SaveThread()` and `C.PyEval_RestoreThread(tState)`).
 
-#### Setup (for dev)
+So if you're wondering why Python2 still comes into it here and there- that's why. Doesn't seem to cause any problems.
 
-Ensure both go and pkg-config are installed.
+## Prerequisites
 
-* ```mkvirtualenvwrapper -p (/path/to/pypy) gosnmp-python```
-* ```pip install -r requirements-dev.txt```
-* ```./build.sh```
-* ```GODEBUG=cgocheck=0 py.test -v```
+- MacOS
+- CPython3.8+
+- virtualenv
+    - `pip install virtualenv`
+- pkgconfig
+    - `brew install pkg-config`
+- Docker
 
-#### What's worth knowing if I want to further the development?
-
-* gopy doesn't like Go interfaces; so make sure you don't have any public (exported) interfaces
-    * this includes a struct with a public property that may eventually lead to an interface
-
-#### Example Go RPCSession usage (simple session ID, calls return JSON)
-
-There's no real reason why you'd want to do this (just use gosnmp on it's own)- it's more for reference:
+## Install (from PyPI)
 
 ```
-package main
-
-import (
-	"gosnmp_python"
-	"fmt"
-)
-
-func main() {
-
-	sessionID := gosnmp_python.NewRPCSessionV2c(
-		"1.2.3.4",
-		161,
-		"public",
-		5,
-		1,
-	)
-
-	err := gosnmp_python.RPCConnect(sessionID)
-	if err != nil {
-		panic(err)
-	}
-
-	jsonResult, err := gosnmp_python.RPCGet(sessionID, ".1.3.6.1.2.1.1.5.0")
-	if err != nil {
-		panic(err)
-	}
-
-	fmt.Println(jsonResult)
-
-	err = gosnmp_python.RPCClose(sessionID)
-	if err != nil {
-		panic(err)
-	}
-
-}
+python -m pip install gosnmp-python
 ```
 
-#### Example Python usage (uses RPCSession underneath because of memory leaks between Go and Python with structs)
-
-To create an SNMPv2 session in Python do the following:
+## Setup
 
 ```
-from gosnmp_python import create_snmpv2c_session
-
-session = create_snmpv2c_session(
-    hostname='1.2.3.4',
-    community='public',
-)
-
-session.connect()
-
-print session.get('.1.3.6.1.2.1.1.5.0')
-
-session.close()
+virtualenv -p $(which python3) venv
+source venv/bin/activate
+./fix_venv.sh
+pip install -r requirements-dev.txt
 ```
 
-Which returns an object like this:
+## Build
 
 ```
-SNMPVariable(
-    oid='.1.3.6.1.2.1.1.5', 
-    oid_index=0, 
-    snmp_type=u'bytearray', 
-    value='hostname.domain.com.au'
-)
+source venv/bin/activate
+./native_build.sh
 ```
 
-Some of this may feel a bit like [easysnmp](https://github.com/kamakazikamikaze/easysnmp); that's intentional, I was originally using that
-but I think its got some underlying thread-safety issues on the C side (particularly to do with SNMPv3).
+If you're deep in the grind and want to iterate faster, you can invoke:
 
-No offence to the guys that contribute to that project- it's served me very well.
-
-To use the test build container...
-
-    ./test.sh
-
-To shell into the test container to have a look around...
+```
+./native_build.sh fast
+```
 
-    ./test.sh bash
+This skips the setup (assuming you've already done that).