Disallow self.* calls to public functions

docs/installing-vyper.rst

@@ -156,7 +156,7 @@ Additionally, you may try to compile an example contract by running:
     vyper examples/crowdfund.vy
 
 If everything works correctly, you are now able to compile your own smart contracts written in Vyper.
-If any unexpected errors or exceptions are encountered, please feel free create an issue <https://github.com/ethereum/vyper/issues/new>.
+If any unexpected errors or exceptions are encountered, please feel free to `create an issue <https://github.com/ethereum/vyper/issues/new>`_.
 
 .. note::
     If you get the error `fatal error: openssl/aes.h: No such file or directory` in the output of `make`, then run `sudo apt-get install libssl-dev1`, then run `make` again.

docs/structure-of-a-contract.rst

@@ -36,27 +36,52 @@ Functions are the executable units of code within a contract.
     // ...
 
 Function calls can happen internally or externally and have different levels of visibility (see
-:ref:`structure-decorators`) towards other contracts. Functions must be decorated with either
-@public or @private.
+:ref:`structure-decorators`) towards other contracts. Functions must be explicitely declared as public or private.
+
+Public Functions
+----------------
+
+Public functions (decorated with ``@public``) are a part of the contract interface and may be called via transactions or from other contracts. They cannot be called internally.
+
+Public functions in Vyper are equivalent to external functions in Solidity.
+
+Private Functions
+-----------------
+
+Private functions (decorated with ``@private``) are only accessible from other functions within the same contract. They are called via the ``self`` variable:
+
+::
+
+    @private
+    def _times_two(amount: uint256) -> uint256:
+        return amount * 2
+
+    @public
+    def calculate(amount: uint256) -> uint256:
+        return self._times_two(amount)
+
+Private functions do not have access to ``msg.sender`` or ``msg.value``. If you require these values within a private function they must be passed as parameters.
 
 .. _structure-decorators:
 
 Decorators
 ----------
 
-============================= ===========================================
-Decorator                     Description
-============================= ===========================================
-`@public`                     Can be called from external contracts.
-`@private`                    Can only be called within current contract.
-`@constant`                   Does not alter contract state.
-`@payable`                    The contract is open to receive Ether.
-`@nonreentrant(<unique_key>)` Function can only be called once,
-                              both externally and internally. Used to
-                              prevent reentrancy attacks.
-============================= ===========================================
+The following decorators are available:
 
-The visibility decorators `@public` or `@private` are mandatory on function declarations, whilst the other decorators(@constant, @payable, @nonreentrant) are optional.
+=============================== ===========================================
+Decorator                       Description
+=============================== ===========================================
+``@public``                     Can only be called externally.
+``@private``                    Can only be called within current contract.
+``@constant``                   Does not alter contract state.
+``@payable``                    The contract is open to receive Ether.
+``@nonreentrant(<unique_key>)`` Function can only be called once,
+                                both externally and internally. Used to
+                                prevent reentrancy attacks.
+=============================== ===========================================
+
+The visibility decorators ``@public`` or ``@private`` are mandatory on function declarations, whilst the other decorators(``@constant``, ``@payable``, ``@nonreentrant``) are optional.
 
 Default function
 ----------------
@@ -165,120 +190,172 @@ Additional information about Ethereum Natural Specification (NatSpec) can be fou
 Contract Interfaces
 ===================
 
-Vyper supports exporting and importing contract interfaces, this is done using a `import` and `implements` statements.
+An interface is a set of function definitions used to enable communication between smart contracts. A contract interface defines all of that contract's publicly available functions. By importing the interface, your contract now knows how to call these functions in other contracts.
 
-::
+Defining Interfaces and Making External Calls
+---------------------------------------------
 
-    import an_interface as FooBarInterface
+Interfaces can be added to contracts either through inline definition, or by importing them from a seperate file.
 
-    implements: FooBarInterface
+The ``contract`` keyword is used to define an inline external interface:
 
-This will import the defined interface in vyper file at `an_interface.vy` (or `an_interface.json` if using ABI json interface type) and make sure the current contract implements all the necessary public functions.
-Note that all interface is valid vyper code, without the return type check. Meaning you can use a contract with code in in the function body as interface as well (but default to a function body with a `pass`).
+.. code-block:: python
 
-Extracting Interfaces
----------------------
+    contract FooBar:
+        def calculate() -> uint256: constant
+        def test1(): modifying
 
-Vyper has a built-in format option to allow you to make your own vyper interfaces easily.
+The defined interface can then be use to make external calls, given a contract address:
+
+.. code-block:: python
+
+    @public
+    def test(some_address: address):
+        FooBar(some_address).calculate()
+
+The interface name can also be used as a type annotation for storage variables. You then assign an address value to the variable to access that interface. Note that assignment of an address requires the value to be cast using the contract type e.g. ``FooBar(<address_var>)``:
+
+.. code-block:: python
+
+    foobar_contract: FooBar
+
+    @public
+    def __init__(foobar_address: address):
+        self.foobar_contract = FooBar(foobar_address)
+
+    @public
+    def test():
+        self.foobar_contract.calculate()
+
+Specifying ``modifying`` annotation indicates that the call made to the external contract will be able to alter storage, whereas the ``constant`` call will use a ``STATICCALL`` ensuring no storage can be altered during execution.
 
 ::
 
-    vyper -f interface examples/voting/ballot.vy
+    contract FooBar:
+        def calculate() -> uint256: constant
+        def test1(): modifying
 
-    # Functions
+    @public
+    def test(some_address: address):
+        FooBar(some_address).calculate()  # cannot change storage
+        FooBar(some_address).test1()  # storage can be altered
+
+
+Importing Interfaces
+--------------------
+
+Interfaces are imported with ``import`` or ``from ... import`` statements.
+
+Imported interfaces are written using standard Vyper syntax, with the body of each function replaced by a ``pass`` statement:
+
+.. code-block:: python
 
-    @constant
     @public
-    def delegated(addr: address) -> bool:
+    def test1():
         pass
 
-    # ...
+    @public
+    def calculate() -> uint256:
+        pass
 
-If you want to do an external call to another contract, vyper provides an external contract extract utility as well.
+You can also import a fully implemented contract and Vyper will automatically convert it to an interface.
 
-::
+Imports via ``import``
+~~~~~~~~~~~~~~~~~~~~~~
 
-    vyper -f external_interface examples/voting/ballot.vy
+With absolute ``import`` statements, you **must** include an alias as a name for the imported package. In the following example, failing to include ``as Foo`` will raise a compile error:
 
-    # External Contracts
-    contract Ballot:
-        def delegated(addr: address) -> bool: constant
-        def directlyVoted(addr: address) -> bool: constant
-        def giveRightToVote(voter: address): modifying
-        def forwardWeight(delegate_with_weight_to_forward: address): modifying
-        # ...
+.. code-block:: python
 
-The output can then easily be copy-pasted to be consumed.
+    import contract.foo as Foo
 
-Built-in Interfaces
--------------------
+Imports via ``from ... import``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Vyper supports a few built-in interfaces such as ERC20 and ERC721. These are imported from ``vyper.interfaces``:
+Using ``from`` you can perform both absolute and relative imports. With ``from`` import statements you **cannot** use an alias - the name of the interface will always be that of the file:
 
-::
+.. code-block:: python
 
-  from vyper.interfaces import ERC20
+    from contract import foo
 
-  implements: ERC20
+Relative imports are possible by prepending dots to the contract name. A single leading dot indicates a relative import starting with the current package. Two leading dots indicate a relative import from the parent of the current package:
 
-External Calls Using Interfaces
--------------------------------
+.. code-block:: python
 
-To define external interfaces inline the `contract` keyword is used.
+    from . import foo
+    from ..interfaces import baz
+
+Searching For Interface Files
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When looking for a file to import Vyper will first search relative to the same folder as the contract being compiled. For absolute imports, it also searches relative to the root path for the project. Vyper checks for the file name with a ``.vy`` suffix first, then ``.json``.
+
+When using the command line compiler, the root path defaults to to the current working directory. You can change it with the ``-p`` flag:
 
 ::
 
-    contract FooBar:
-        def test1(): modifying
-        def calculate() -> uint256: constant
+    $ vyper my_project/contracts/my_contract.vy -p my_project
+
+In the above example, the ``my_project`` folder is set as the root path. A contract cannot perform a relative import that goes beyond the top-level folder.
 
-The defined inline contract can then be use to make external calls, given a contract address.
+Built-in Interfaces
+-------------------
 
-Specifying `modifying` annotation indicates that the call made to the external contract will be able to alter storage, whereas the `constant` call will use a `STATICCALL` ensuring no storage can be altered during execution.
+Vyper includes common built-in interfaces such as `ERC20 <https://eips.ethereum.org/EIPS/eip-20>`_ and `ERC721 <https://eips.ethereum.org/EIPS/eip-721>`_. These are imported from ``vyper.interfaces``:
 
-::
+.. code-block:: python
 
-    @public
-    def test(some_address: address):
-        FooBar(some_address).calculate()  # can not change storage
-        FooBar(some_address).test1()  # storage can be altered
+    from vyper.interfaces import ERC20
 
-An additional utility of storing a contract address in a contract is defined by the ``<global_var>: FooBar`` annotation. Note that assignment of an address requires the address value to be casted using the contract type e.g. ``FooBar(<address_var>)``.
+    implements: ERC20
 
-::
+You can see all the available built-in interfaces in the `Vyper GitHub <https://github.com/ethereum/vyper/tree/master/vyper/interfaces>`_ repo.
 
-    foobar_contract: FooBar
 
-    @public
-    def __init__(foobar_address: address):
-        self.foobar_contract = FooBar(foobar_address)
+Implementing an Interface
+-------------------------
 
-    @public
-    def call_test1():
-      # ...
+You can define an interface for your contract with the ``implements`` statement:
 
-To import interfaces to be used in externals calls, one uses the interface just as one would use an inlined interface definition.
+.. code-block:: python
+
+    import an_interface as FooBarInterface
+
+    implements: FooBarInterface
+
+
+This imports the defined interface from the vyper file at ``an_interface.vy`` (or ``an_interface.json`` if using ABI json interface type) and ensures your current contract implements all the necessary public functions. If any interface functions are not included in the contract, it will fail to compile. This is especially useful when developing contracts around well-defined standards such as ERC20.
+
+Extracting Interfaces
+---------------------
+
+Vyper has a built-in format option to allow you to make your own vyper interfaces easily.
 
 ::
 
-    import foo_bar as FooBar
+    $ vyper -f interface examples/voting/ballot.vy
 
-    foobar_contract: FooBar
+    # Functions
 
+    @constant
     @public
-    def __init__(foobar_address: address):
-        self.foobar_contract = FooBar(foobar_address)
+    def delegated(addr: address) -> bool:
+        pass
 
-    @public
-    def test():
-        self.foobar_contract.one()
+    # ...
 
-Or alternatively
+If you want to do an external call to another contract, vyper provides an external contract extract utility as well.
 
 ::
 
-    import foo_bar as FooBar
+    $ vyper -f external_interface examples/voting/ballot.vy
 
-    @public
-    def test(addy: address):
-      FooBar(addy).one()
+    # External Contracts
+    contract Ballot:
+        def delegated(addr: address) -> bool: constant
+        def directlyVoted(addr: address) -> bool: constant
+        def giveRightToVote(voter: address): modifying
+        def forwardWeight(delegate_with_weight_to_forward: address): modifying
+        # ...
+
+The output can then easily be copy-pasted to be consumed.

docs/testing-contracts.rst

@@ -26,7 +26,7 @@ Vyper Contract and Basic Fixtures
 This is the base requirement to load a vyper contract and start testing. The last two fixtures are optional and will be
 discussed later. The rest of this chapter assumes, that you have this code set up in your ``conftest.py`` file.
 Alternatively, you can import the fixtures to ``conftest.py`` or use
-`pytest_plugins <https://docs.pytest.org/en/latest/plugins.html>`_.
+`pytest plugins <https://docs.pytest.org/en/latest/plugins.html>`_.
 
 Load Contract and Basic Tests
 =============================