Package: ens
Access the Ethereum Name Service using this python library. Note:this
is a work in progressUsing this library is not a way to skip learning how ENS works. If you
are registering a name, a small misunderstanding can cause you to loseallyour deposit. Goread about
ENSfirst. Your
funds are your responsibility.Beta-quality warningThis is a preview for developers, and an invitation for contributions.
Please do not use this in production until this warning is removed,
especially when putting funds at risk. Examples of funds being at risk
include: sending ether/tokens to resolved addresses and participating in
name auctions.If you supply the a domain with typebytes, it will be assumed to be
UTF-8 encoded, like inEthereum
contracts.Setuppip install ensAny issues? SeeSetup detailsUsageAll examples in Python 3Name infoGet address from nameDefault to {name}.eth:from ens import ens


# look up the hex representation of the address for a name

eth_address = ens.address('jasoncarver.eth')

assert eth_address == '0x5b2063246f2191f18f2675cedb8b28102e957458'


# ens.py will assume you want a .eth name if you don't specify a full name

assert ens.address('jasoncarver') == eth_addressGet name from addressdomain = ens.name('0x5b2063246f2191f18f2675cedb8b28102e957458')


# name() also accepts the bytes version of the address

assert ens.name(b'[ c$o!\x91\xf1\x8f&u\xce\xdb\x8b(\x10.\x95tX') == domain


# confirm that the name resolves back to the address that you looked up:

assert ens.address(domain) == '0x5b2063246f2191f18f2675cedb8b28102e957458'Get owner of nameeth_address = ens.owner('exchange.eth')Set up your namePoint your name to your addressDo you want to set up your name so thatens.address()will show the
address it points to?ens.setup_address('jasoncarver.eth', '0x5b2063246f2191f18f2675cedb8b28102e957458')You must already be the owner of the domain (or its parent).In the common case where you want to point the name to the owning
address, you can skip the addressens.setup_address('jasoncarver.eth')You can claim arbitrarily deep subdomains.Gas costs scale up with the
number of subdomains!ens.setup_address('supreme.executive.power.derives.from.a.mandate.from.the.masses.jasoncarver.eth')Wait for the transaction to be mined, then:assert ens.address('supreme.executive.power.derives.from.a.mandate.from.the.masses.jasoncarver.eth') == \
    '0x5b2063246f2191f18f2675cedb8b28102e957458'Point your address to your nameDo you want to set up your address so thatens.name()will show the
name that points to it?This is like Caller ID. It enables you and others to take an account and
determine what name points to it. Sometimes this is referred to as
“reverse” resolution.ens.setup_name('jasoncarver.eth', '0x5b2063246f2191f18f2675cedb8b28102e957458')If you don’t supply the address,setup_namewill assume you want the
address returned byens.address(name).ens.setup_name('jasoncarver.eth')If the name doesn’t already point to an address,ens.setup_namewill
callens.setup_addressfor you.Wait for the transaction to be mined, then:assert ens.name('0x5b2063246f2191f18f2675cedb8b28102e957458') == 'jasoncarver.eth'Auctions for names ending in .ethGet auction statusExample with domain ‘payment.eth’:from ens.registrar import Status


status = ens.registrar.status('payment')


# if you forget to strip out .eth, ens.py will do it for you

assert ens.registrar.status('payment.eth') == status


# these are the possible statuses

assert status in (
  Status.Open,
  Status.Auctioning,
  Status.Owned,
  Status.Forbidden,
  Status.Revealing,
  Status.NotYetAvailable
  )


# if you get the integer status from another source, you can compare it directly

assert Status.Owned == 2Start auctions# start one auction (which tips people off that you're interested)

ens.registrar.start('you_saw_him_repressin_me_didnt_ya')


# start many auctions (which provides a bit of cover)

ens.registrar.start(['exchange', 'tickets', 'payment', 'trading', 'registry'])Bid on auctionBid on a ‘trading.eth’ with 5211 ETH, and secret “I promise I will not
forget my secret”:from web3utils import web3

ens.registrar.bid(
      'trading',
      web3.toWei('5211', 'ether'),
      "I promise I will not forget my secret",
      transact={'from': web3.eth.accounts[0]}
      )(if you want to “mask” your bid, set a higher value in the transact
dict)Reveal your bidYou mustalwaysreveal your bid, whether you won or lost. Otherwise
you will lose the full deposit.Example of revealing your bid on ‘registry.eth’ with 0.01 ETH, and
secret “For real, though: losing your secret means losing ether”:ens.registrar.reveal(
      'registry',
      web3.toWei('0.01', 'ether'),
      "For real, though: losing your secret means losing ether",
      transact={'from': web3.eth.accounts[0]}
      )Claim the name you wonaka “Finalize” auction, which makes you the owner in ENS.ens.registrar.finalize('gambling')Get detailed information on an auctionFind out the owner of the auction Deed – seedocs on the
differencebetween owning the name and the deeddeed = ens.registrar.deed('ethfinex')

assert deed.owner() == '0x9a02ed4ca9ad55b75ff9a05debb36d5eb382e184'When was the auction completed? (a timezone-aware datetime object)close_datetime = ens.registrar.close_at('ethfinex')

assert str(close_datetime) == '2017-06-05 08:10:03+00:00'How much is held on deposit?from decimal import Decimal

deposit = ens.registrar.deposit('ethfinex')

assert web3.fromWei(deposit, 'ether') == Decimal('0.01')What was the highest bid?top_bid = ens.registrar.top_bid('ethfinex')

assert web3.fromWei(top_bid, 'ether') == Decimal('201709.02')Setup detailsIf Python 2 is your default, or you’re not sureIn your shellif pip --version | grep "python 2"; then
  python3 -m venv ~/.py3venv
  source ~/.py3venv/bin/activate
fiNow, with Python 3In your shell:pip install ensens.pyrequires an up-to-date Ethereum blockchain, preferably local.
If your setup isn’t working, try runninggeth--fastuntil it’s
fully-synced. I highly recommend using the default IPC communication
method, for speed and security.“No matching distribution found for ens”If you are seeing something like:Collecting ens
  Could not find a version that satisfies the requirement ens (from versions: )
No matching distribution found for ensThen retry the first Setup section, to make sure you’re in Python 3Optionally, a custom web3 providerIn Python:from ens import ENS
from web3 import IPCProvider

ens = ENS(IPCProvider('/your/custom/ipc/path'))Developer Setupgit clone git@github.com:carver/ens.py.git
cd ens.py/

python3 -m venv venv
. venv/bin/activate

pip install -e .
pip install -r requirements-dev.txtTesting SetupRe-run flake on file changes:$ when-changed -s -1 -r ens/ tests/ -c "clear; echo; echo \"running flake - $(date)\"; warn()
{
notify-send -t 5000 'Flake8 failure ⚠⚠⚠⚠⚠' 'flake8 on ens.py failed'
}
if ! git diff | flake8 --diff | grep "\.py"; then if ! flake8 ens/ tests/; then warn; fi else warn; fi; echo done"Why does ens.py require python 3?Short versionIt turns out that the distinction betweenstrandbytesis
important. If you want to write code for the future (Ethereum), don’t
use a language from the past.Long versionInteracting with the EVM requires clarity on the bits you’re using. For
example, a sha3 hash expects to receive a series of bytes to process.
Calculating the sha3 hash of a string is (or should be) a Type Error;
the hash algorithm doesn’t know what to do with a series of characters,
aka Unicode code points. As the caller, you need to know which thing
you’re calculating the hash of: 1. a series of bytes:b'[c$o!\x91\xf1\x8f&u\xce\xdb\x8b(\x10.\x95tX'2. the bytes
represented by a string in hex format:'0x5b2063246f2191f18f2675cedb8b28102e957458'3. the bytes generated
by encoding a string using utf-8:Oops, the bytes from #1 cannot be
read using utf-8!4. the bytes generated by encoding a string using
utf-16:'⁛④Ⅿ\uf191⚏칵诛ဨ键塴'Python 3 doesn’t let you ignore a lot of these details. That’s good,
because precision in dealing with the EVM is critical. Ether is at
stake.If you are resistant – I get it, I’ve been there. It is not intuitive
for most people. But it’s seriously worth it tolearn about
encodingif you’re going to develop on top of Ethereum. Your ETH depends on it!