# netifaces (2)

## 1. What is this?

The original [netifaces](https://github.com/al45tair/netifaces) was abandonned by it's maintainer,
leaving us without the option to get network addresses of any kind in Python. Unfortunately, the
original sources are more akin to arcane magic, so picking where it's been left off is a difficult
task.

I decided to rewrite `netifaces`, keeping the **almost** exact same API and adding the following:

- Support for future python versions
- Type annotations
- Maybe a more "queriable" API in the future

This project aims to be a drop-in replacement for those project who use `netifaces`, but I do not
guarantee anything.


### 1.1 What is not working **right-now**

- The `gateways` API is only working if your system has a `/proc/net/route` file or the `ip` tool
- The `windows` gateways API is non-functional

## 2. Usage

For now the API is the same as the original `netifaces`, so please refer to [it](https://github.com/al45tair/netifaces).

Install:
```shell
pip install netifaces2
```

Import:
```python
>>> import netifaces
>>> netifaces.interfaces()  
    ...
>>> netifaces.ifaddresses('en0')
    ...
>>> netifacs.gateways()
    ...
```

## 3. API differences between this and al45tair/netifaces

### `gateways`

The `gateways` function does not support indexing through the `default` special key. This is because it makes a
sane typing definition difficult to write and be understandable. Instead, if you want the same functionality,
the following is exposed:

```python
>>> netifaces.default_gateway()
    ...
```

The result will be the default gateway for each interface type. The result may
be an empty dict if no default route is set.

The level of completness differs a little bit with the original version; some
address families might not yet be available and `PEER` addresses are not
reported for now. If you need a feature, open an issue and I will do my best to
add it.

Gateways also returned the interfaces indexed by integer values. This is a bit
odd (IMO) since the integers values for the interface types are
system-dependent. Enum values with a more semantic meaning are now used (they
        are still tied to linux numbers), but you can use `old_api=True` in
their call to get the al45air-style keys back.

### `AF_` Constants

In the previous version of `netifaces` the `AF_` constants' value were assigned
to be platform independent. This has the nice effect of abstracting the OS when
accessing the information of a network layer. However after consideration, it
does not feel like the right place to provide abstraction. If you update your
project's dependencies to this version of `netifaces`, be wary of this change.
For instance, on linux you may need to replace `AF_LINK` with `AF_PACKET` to get
mac addresses.

In the future, an extra API will allow accessing a specific layer's information
by querying for it, without using the platform's constant.

## 4. Platform support

### Wheels
Building Linux, Windows and macOS cp37-abi3 wheels (requires Python 3.7 and newer)  
Install using pip:  
`python -m pip install netifaces2`

#### Linux  
Linux cp37-abi3 wheels are built on manylinux2_17 aka manylinux2014 and require pip>=19.3  
cp36m-manylinux2_17 wheels are unsupported and are being built only as a fallback
for systems with only Python 3.6 available.

## 5. License

This software is distributed under a MIT license.

## 6. Developing Locally

To set up for local development, you will first need to install Rust from [rustup](https://rustup.rs/).

It's then recommended to create a virtual environment and install the package plus its dependencies into it:
```
$ python3 -m venv venv
$ source venv/bin/activate (or .\venv\Scripts\activate.ps1 with Windows Powershell)
$ python3 -m pip install -e '.[dev]' # This internally runs the Rust compiler
$ python3 -m pip install pre-commit
$ source venv/bin/activate # Re-source the venv to pick up new scripts
$ pre-commit install
```

To recompile the rust code after making changes, run:
```
$ python3 -m pip install -e .
```
again.
