Setting Up Your Project

However you structure your project, you’ll need something to tell PyPI what’s in your package and how to set the package up. I created a setup.py file for that:

# setup.py

import pathlib
from setuptools import setup, find_packages


here = pathlib.Path(__file__).parent
readme = (here / "README.md").read_text()

extras_require = (here / "requirements.txt").read_text().splitlines()


setup(
    name="pyautoreloadserver",
    version="0.0.1",
    author="Jay Ess",
    description="A simple HTTP server that reloads when a file change is detected",
    url="https://github.com/jay3ss/pyautoreloadserver",
    long_description=readme,
    long_description_content_type="text/markdown",
    packages=find_packages(),
    classifiers=[
        "Development Status :: 5 - Production/Stable",
        "Intended Audience :: Developers",
        "License :: OSI Approved :: MIT License",
        "Programming Language :: Python :: 3",
        "Programming Language :: Python :: 3.11",
    ],
    extras_require={"dev": extras_require},
    entry_points={
        "console_scripts": [
            "pyautoreloadserver = pyautoreloadserver.cli:main",
        ],
    },
    package_dir={
        "tests": "tests",
        "pyautoreloadserver": "pyautoreloadserver",
    },
)

You can read all about what to put in your own setup.py file here. I like to use code to keep things like the long_description and extras_require attributes up-to-date automatically. But, you do you.

Now, make an account on PyPI’s website and then get an API key that you’ll use to upload your package. I made a ~/.pypirc file to hold all of the information that I’ll need to upload my packages. Here’s what it looks like (with some info redacted):

# ~/.pypirc

[distutils]
index-servers =
    pypi
    pypitest

[pypitest]
repository = https://test.pypi.org/legacy/
username = __token__
password = <api-key>

[pypi]
username = __token__
password = <api-key>

There’s couple of things going on in the file above and you should checkout the docs for it. But, in the meantime here’s some of the important bits from the docs

The distutils section defines an index-servers field that lists the name of all sections describing a repository.

Each section describing a repository defines three fields:

• repository: The URL of the repository.
• username: The registered username on the repository.
• password: The password that will used to authenticate the username.

The [distutils]’s index-servers field is where you define additional repositories. Note that my ~/.pypirc file doesn’t have a repository field for the pypi section. That’s because the default value for that field for the [pypi] section is https://upload.pypi.org/legacy. Also, if you’re using an API token like I am then for the username field you literally put __token__ as the value. It took me an embarrassingly long time to figure that one out.

Building the Package for Distribution

There are a multiple ways to build a Python package for distribution. The two that I come across the most are directly using a setup.py script (which is strongly discouraged and deprecated) or using the build package. I’m going to use the build package.

I was having trouble using build the command python -m build and had to modify it slightly

python -m build --no-isolation --wheel

# this can be simplified by using -n and -w, respectively

which seemed to work. The --no-isolation flag prevents build from using an isolated virtual environment (and makes the build time shorter) and the --wheel flags tells build to create a wheel and a build/ and dist/ directory.

Publishing the Package

Next, use twine to publish the package. Twine is the official PyPI upload tool so it should work for you. You’ll first want to test publishing your package to ensure that everything goes right. Using twine it’s pretty easy to test uploading.

python -m twine upload -r pypitest dist/* --verbose

The -r flag tells twine which repository we want to upload to (pypitest here) and then dist/* is the location of the wheel. The --verbose flag gives us more output from twine so if there’s a problem we can have a better idea what it is.

If everything went well go ahead and move on to uploading to PyPI. The command for that is exactly the same as loading to the test PyPI repository, but instead we use the value pypi for the -r flag

python -m twine upload -r pypi dist/* --verbose

If nothing went wrong your package should be live on PyPI. Have a question? Leave a comment (if I’ve re-enabled comments) or leave an issue or pull request on the site’s repo.

Cloning a Repository

git clone git@github.com:<username>/<reponame>.git

Changing the Remote to Use SSH

If you’ve already cloned a repo without using SSH, then you can modify the branch to use SSH

git remote set-url origin git@github.com:<username>/<reponame>.git

General Form of a Complex Number

According to Wikipedia, complex numbers are

[…] regarded in the mathematical sciences as just as “real” as the real numbers, and are fundamental in many aspects of the scientific description of the natural world.

Complex numbers can be written in two forms: rectangular and polar. They live in the 2-dimensional complex plane with the horizontal axis is called the “real” axis while the vertical axis is called the “imaginary” axis. The figure below shows this nicely.

Note that in electrical engineering denotes the imaginary number/axis so as to avoid confusion with the time-varying current . This is the notation that I’ll be using throughout this article. If this confuses you, then just replace every instance of with .

Polar Form

The rectangular form of a complex number is as follows

and is shown in the figure below.

is the magnitude and is the phase angle of the complex number , respectively. To help explain this, you can think of a complex number as a vector in the complex plane with the magnitude being the length of the vector and the phase angle the direction.

Converting Between Forms

It’s often useful (or necessary) to convert from one form to another to either get information (such as magnitude) or to aid in calculations (adding complex numbers is easier when both numbers are in rectangular form).

Arithmetic Operations

Now that we know how to convert from one form to another, we can perform arithmetic operations with complex numbers.

Complex Conjugate

Every complex number has a complex conjugate and that conjugate is found by switching the signs of the imaginary component. For example, if we have a complex number then its complex conjugate is . Notice how only the sign of the imaginary component became negative and the real component’s sign remained the same. Because we’re just switching signs of the imaginary component, you can think of the complex conjugate as a reflection about the real axis. Also note the next to the variable . This is one of the notations to denote a complex conjugate.

Complex conjugates are very important in math, physics, and engineering and you should definitely read about the importance of complex conjugates.

Conclusion

In this article, we learned about the different forms of a complex number and how to convert between them. We also learned how to add, subtract, multiply, and divide complex numbers. Finally, we learned how to find the complex conjugate of a complex number as well. If you have any comments or questions, please comment below.

References

1. Wikipedia - List of things named after Leonhard Euler

Declaring a Struct

The example below shows the semantics of declaring a struct. Just replace whatever is inside of the <...> with the appropriate text.

struct <tag>
{
    <data-type> <member-name>;
    // more declarations...
};  // notice the semicolon

For example

• <tag>: is the name of the struct, so Student
• <data-type>: is the data type of the member (variable), so int
• <member-name>: is the name of the member (variable), so id

Put it all together (plus some additional members) and we have

struct Student
{
    int id;             // Student's ID number
    std::string name;   // Student's name
    float gpa;          // Student's GPA
    int gradeLevel;     // Students current grade level (e.g., 11)
};

Notice how I left the tag (Student) capitalized? I like to do that so when I’m reading my code I can easily spot the declaration of a struct. This Student struct is basically a new data type and we can use it as such.

Defining a Struct Variable

It’s no different defining a variable of type Student than it is of int or double. For example,

Student student;

We just declared a variable named student with the type of Student. Simple!

Student student = {5678, "A. Student", 4.0, 12};

Student stu1 = {6789, "Billy"}; // works
Student stu2 = {6789, 4.0, 12}; // does not work, skipped "name"

Using a Struct

We use the dot (.) operator to set and access the members of a struct like below

Student johnny;
johnny.id = 1234;
johnny.name = "Johnny B. Goode";
johnny.gpa = 1.1;
johnny.gradeLevel = 7;

// Student johnny = {1234, "Johnny B. Goode", 1.1, 7} // also works

std::cout << "ID:\t\t" << johnny.id << "\n"
          << "Name:\t\t" << johnny.name << "\n"
          << "GPA:\t\t" << johnny.gpa << "\n"
          << "Grade Level:\t" << johnny.gradeLevel << "\n";

After we compile and run this, the output will be

ID:             1234
Name:           Johnny B. Goode
GPA:            1.1
Grade Level:    7

This may seem like a lot of work, but its usefulness becomes immediately clear when we have multiple students.

Array of Structs

Instead of having to declare multiple arrays (or vectors) or variables we can declare an array (or vector) of type Student and use a loop to set or access the members of each element of the array (or vector). For example

// const int NUMBER_OF_STUDENTS = <pick a number>;
Student students[NUMBER_OF_STUDENTS];

// Set the member for each element of the array
for (int i = 0; i < NUMBER_OF_STUDENTS; i++)
{
    std::cout << "Enter student ID: ";
    std::cin >> students[i].id;
    std::cin.ignore();

    std::cout << "Enter student name: ";
    std::getline(std::cin, students[i].name);

    std::cout << "Enter student GPA: ";
    std::cin >> students[i].gpa;

    std::cout << "Enter student grade level: ";
    std::cin >> students[i].gradeLevel;

    std::cout << std::endl;
}

// Print out the member for each element of the array
for (int i = 0; i < NUMBER_OF_STUDENTS; i++)
{
    std::cout << "Student #" << (i + 1) << "\n"
                << "ID:\t\t" << students[i].id << "\n"
                << "Name:\t\t" << students[i].name << "\n"
                << "GPA:\t\t" << students[i].gpa << "\n"
                << "Grade Level:\t" << students[i].gradeLevel << "\n";

    std::cout << std::endl;
}

Pointer to Structs

You define a pointer to a struct in the exact same way that you’d define a pointer to any other data type

Student* student;

Using a pointer to a struct is a little bit more involved. If you need to use a pointer to a struct then you have a couple of options with one of them being much easier and the preferred way.

std::cout << *student.name;

std::cout << (*student).name;

std::cout << student->name;

Array Members

Structs can have an array as a member, but you have to take care of how you define them. Member arrays must have their lengths defined in the definition of the struct unless it’s the last member of the struct [1]. For example,

// Will compile, flexible length member array declared
// as last member
struct Testing1
{
    int number;
    int numbers[];
};

// Won't compile, member array length not declared
struct Testing2
{
    int numbers[];
    int number;
}

// Will compile, member array length declared
struct Testing3
{
    int numbers[5];
    int number;
};

To use an array member, you use it just like any other array

Testing3 testing;
for (int i = 0; i < 5; i++)
{
    testing.numbers[i] = i;
}

Nested Structs

You can also have nested structs (one within another). This is done in the same manner that you’d define any other member. For example, we can create a new struct that holds a US address

struct Address
{
    std::string street;
    std::string city;
    int zipcode;
    std::string state;
};

and now we can update our Student struct to include the Address struct

struct Student
{
    int id;
    std::string name;
    float gpa;
    int gradeLevel;
    Address address
};

To access member struct, we use the dot notation twice

Student student;
student.address.street = "123 Fake St.";
student.address.city = "Springfield";
student.address.zipcode = 97475;
student.address.state = "OR";

Or, if we’re using a pointer to a struct we use the arrow and dot operators together

Student* student;
student->address.street = "123 Fake St.";
student->address.city = "Springfield";
student->address.zipcode = 97475;
student->address.state = "OR";

Conclusion

We’ve learned what a struct is, what it’s used for, and different ways of using structs. Now, go on and make use of this knowledge to create some great programs!

References

1. Starting out with C++: From Control Structure Through Objects, 8th Edition
2. Structures in C++ - Tutorial - Cprogramming.com

What We Have So Far

So far, we’ve implemented the is_empty and push methods. Before we get going it’s a good idea to take a step back and see the big picture. Let’s take a look at what we have at the moment

class LinkedStack(StackInterface):
    """Defines a link-based stack"""
    def __init__(self):
        self.top = None

    def is_empty(self):
        """Determines if the stack is empty"""
        return self.top is None

    def push(self, entry):
        """Adds a new entry to the top of the stack"""
        node = Node(data=entry)
        if self.is_empty():
            self.top = node
        else:
            node.next = self.top
            self.top = node

        return True

def pop(self):
    """Removes the top of the stack"""
    if self.is_empty():
        return False

self.top = self.top.next
return True

def pop(self):
    """Removes the top of the stack"""
    if self.is_empty():
        return False

    self.top = self.top.next
    return True

def pop(self):
    """Removes the top of the stack"""
    can_pop = not self.is_empty()
    if can_pop:
        # Advance the top of the stack to the next node
        self.top = self.top.next

    return can_pop

# exception.py
class EmptyException(Exception):
    """Exception that's raised when a data structure is empty"""

def peek(self):
    """Returns the top of the stack"""
    if self.top is None:
        raise EmptyException("Stack is empty")

    return self.top.data

def __repr__(self):
    nodes = []
    curr = self.top
    while curr:
        nodes.append(repr(curr))
        curr = curr.next

    return '[' + ', '.join(nodes) + ']'

# interface.py
import abc


class StackInterface(abc.ABC):
    """An abstract base class that defines a stack"""
    @abc.abstractmethod
    def is_empty(self):
        """Determines if the stack is empty"""

    @abc.abstractmethod
    def peek(self):
        """Returns the top of the stack"""

    @abc.abstractmethod
    def pop(self):
        """Removes the top of the stack"""

    @abc.abstractmethod
    def push(self, entry):
        """Adds data to the top of the stack"""

    @abc.abstractmethod
    def push(self, entry):
        """Adds a new entry to the top of the stack"""


# stack.py
from exception import EmptyException
from interface import StackInterface
from node import Node


class LinkedStack(StackInterface):
    """Defines a link-based stack"""
    def __init__(self):
        self.top = None

    def is_empty(self):
        """Determines if the stack is empty"""
        return self.top is None

    def peek(self):
        """Returns the top of the stack"""
        if self.is_empty():
            raise EmptyException("Stack is empty")

        return self.top.data

    def pop(self):
        """Removes the top of the stack"""
        can_pop = not self.is_empty()
        if can_pop:
            # Advance the top of the stack to the next node
            self.top = self.top.next

        return can_pop

    def push(self, entry):
        """Adds a new entry to the top of the stack"""
        node = Node(data=entry)
        if not self.top:
            self.top = node
        else:
            node.next = self.top
            self.top = node

        return True

    def __repr__(self):
        nodes = []
        curr = self.top
        while curr:
            nodes.append(repr(curr))
            curr = curr.next

        return '[' + ', '.join(nodes) + ']'


# node.py
class Node:
    """A node in a chain"""

    def __init__(self, next=None, data=None):
        self.next = next
        self.data = data

    def __repr__(self):
        return repr(self.data)


# exception.py
class EmptyException(Exception):
    """Exception that's raised when a data structure is empty"""

Using the Stack

Let’s play around with the stack a little using the REPL (I prefer IPython). We can make sure we’ve met our specifications. As a recap, here they are

1. (new Stack()).isEmpty() = True
2. (new Stack()).pop() = False
3. (new Stack()).peek() = error
4. (a_stack.push(item)).isEmpty() = False
5. (a_stack.push(item)).peek() = item
6. (a_stack.push(item)).pop() = True

So, now let’s fire up that REPL and test out our shiny stack.

In [1]: stack = LinkedStack()

In [2]: stack.is_empty()
Out[2]: True

In [3]: stack.pop()
Out[3]: False

In [4]: stack.peek()

---------------------------------------------------------------------------
EmptyException                            Traceback (most recent call last)
<ipython-input-7-1e84c3c721a3> in <module>
----> 1 stack.peek()

<ipython-input-4-6a54ea098db0> in peek(self)
     11         """Returns the top of the stack"""
     12         if self.is_empt():
---> 13             raise EmptyException("Stack is empty")
     14
     15         return self.top.data

EmptyException: Stack is empty

In [5]: stack.pop()
Out[5]: False

In [6]: stack.push(1)
Out[6]: True

In [7]: stack.is_empty()
Out[7]: False

In [7]: stack.push(2)
Out[7]: True

In [8]: stack.peek()
Out[8]: 2

In [9]: stack.pop()
Out[9]: True

In [10]: stack.peek()
Out[1]: 1

We can see that our stack implements the specifications and works quite nicely. Although this may not be the best (e.g., most efficient) implementation, it does implement the specifications and in a manner that is clear and tells a nice story (i.e., we won’t get killed with this code, hopefully).

Conclusion

In this article, we learned about nodes and the top node and we also implemented the is_empty and push methods. In the next article we’ll finish implementing our LinkedStack class by implementing the pop and peek methods.

A Singly-Linked Stack

Recall that a stack is a data structure that holds data in LIFO order. When new data is added to the stack it is added to the top and when data is removed it is removed from the top. We can also check how many entries are in the stack, check if it’s empty, and get a copy of the top entry too. This is, abstractly, what a stack is. But, what is a singly-linked stack?

A singly-linked stack holds its data as chain of nodes. Each node in the chain holds the data and a reference to the next node in the chain such as shown in the figure below (recycled from the previous post). We need this reference to the next node because it can be anywhere in memory.

class LinkedStack(StackInterface):
    """Defines a link-based stack"""

# node.py
class Node:
    """A node in a chain"""

    def __init__(self, next=None, data=None):
        self.next = next
        self.data = data

    def __repr__(self):
        return repr(self.data)

def __init__(self):
    self.top = None

def is_empty(self):
    """Determines if the stack is empty"""
    return self.top is None

def push(self, entry):
    """Adds a new entry to the top of the stack"""
    node = Node(data=entry)
    if self.is_empty():
        self.top = node
    else:
        node.next = self.top
        self.top = node

    return True

Conclusion

In this article, we learned about nodes and the top node and we also implemented the is_empty and push methods. In the next article we’ll finish implementing our LinkedStack class by implementing the pop and peek methods.

Resources

1. A link of nodes. Image courtesy of Lasindi

What is a Stack?

A stack is a data structure that holds data in LIFO order. This means that whatever was the most recent “thing” to be put onto the stack will be the first to be removed.

For example, imagine that you are washing a stack of dirty dishes. As you’re washing, every time you clean one plate you pull another off the top of the stack of dirty dishes. If someone wants to give you more dishes to wash they’re going to put them on top of your stack.

That’s pretty much what the stack data structure is. It’s an ordered collection of things (with the most recently added thing at the top) and you can perform certain operations on it. You can

• see if the stack is empty
• see how many things are in it
• take an item off of the top (pop!)
• add something to the top (push!)
• see what the item at the top is (peek!)

We can reword the above list into pseudocode that will make our lives easier when we start writing some code (it’s usually a good idea to put your ideas into pseudocode before writing actual code).

1. (new Stack()).isEmpty() = True
2. (new Stack()).pop() = False
3. (new Stack()).peek() = error
4. (a_stack.push(item)).isEmpty() = False
5. (a_stack.push(item)).peek() = item
6. (a_stack.push(item)).pop() = True

In order, this is what they mean

1. A new stack should be empty
2. You can’t take something off the top of an empty stack
3. Trying to see what’s at the top of an empty stack results in an error
4. A stack with something in it isn’t empty
5. Looking (peeking) at the top gives you the thing that was most recently added
6. You can remove something from a non-empty stack

This may sound somewhat similar to an array. It is, and a stack can be implemented using an array. But, elements in an array can be accessed at will while elements in a stack are accessed in LIFO order.

The Linked Stack

The following discussion is a general discussion about link-based data structures versus array-based data structures. For Python, the overhead of the rest of your code can be so large that the overhead of an array-based vs link-based data structures may not make much of a difference. But, this is still a useful discussion nonetheless.

Think of an array and how every element in an array is stored in contiguous blocks of memory, such as the example in the figure below. Each cell is a block of memory and the number above the cell is its address. When you want to access an element of an array you use an index such as arr[4] to access the fifth element of the array (assuming zero indexing). This is actually an offset from the address of the first element in the array. This gives us quick and direct access to the data. This quick and direct access comes at a cost.

When an array has data added to it and it is, extra memory must be allocated to make room for the data (and then some) and the data must be copied to the new memory location. This is one of the costs of using an array, the time that it takes to allocate more space for the array and copying its data to the newly allocated space. We could preallocate more room for the data ahead of time, but that would be potentially wasted space (this is actually what Python does with lists) and increases the complexity of the data structure.

What about removing data? If we need to remove data at the end of the array then we’re fine. But, removing data anywhere else requires us to either remember which elements have been removed (to guard against stale data), or to readjust all the following elements.

If we’re going to mostly be reading and updating data, or if we know how much space our stack will need then an array is a good choice to use as the data store for a stack. Otherwise, if we’re going to be doing a lot of adding and removing data then we should look into using a linked stack.

A linked stack is made of a set of nodes that are linked together by references, a.k.a the link. Depending on the language, this reference can be a pointer variable (like in C++) or a variable that holds a reference to the next node in the chain (what we’re going to do with Python). (The point is that instead of using contiguous memory addresses a linked stack (or linked data structures in general) use memory from wherever the system allocates space for you. This means that, for the most part, linked stacks can be as large as you need them to be.)

So, a node is an object (don’t think of the CS idea of an object just yet!) that holds data and a reference to another node. If there is no other node, then that reference is None in Python (or, nullptr in C++). In the figure below, the left side of the node is the data and the right side is a reference to the next node indicated by an arrow.

A chain of nodes is shown in the figure below. The head consists of a head node and the nodes following it. The end of the chain is the block all the way to the right with an “X” in it. This “X” represents a reference to None in Python (or nullptr in C++) indicating the end of the chain.

Now, linked data structures aren’t perfect and there will be some tradeoffs to using one versus using an array. First, they take more memory because they must contain a reference to the next node in each node in the chain. Second, they do not support random access. You must start with the head of the structure and traverse the chain until you reach the desired entry.

The Stack Interface

We’re going to start with defining an interface for the stack then move on to implementing the linked stack in the next article. The point of making an interface is to make sure that we implement the correct methods in our implementation. Now, this may not seem like it’s such a big deal right now (after all, we’re only implementing on type of stack, right?), but if we wanted to make a different type of stack then we can inherit from this interface and code to the specifications that are laid out in it (see these answers on SE).

Anyways, we’re going to use Python’s abc module to create an interface that we’ll use later on in our linked stack implementation. By using the abc.ABC class and the abc.abstractmethod decorator, we can insure that who ever uses our interface implements it to the specifications by implementing the methods that use the abc.abstractmethod decorator. If they’re not implemented, then a TypeError will be raised when the class is attempted to be instantiated. You can get the code from a gist on GitHub.

# interfaces.py
import abc


class StackInterface(abc.ABC):
    """An abstract base class that defines a stack"""
    @abc.abstractmethod
    def is_empty(self):
        """Determines if the stack is empty
        :return True if the stack is empty, False otherwise
        """
        pass

    @abc.abstractmethod
    def peek(self):
        """Returns the top of the stack
        :pre The stack isn't empty
        :return The entry at the top of the stack
        """
        pass

    @abc.abstractmethod
    def pop(self):
        """Removes the entry from the top of the stack
        :post The entry at the top of the stack will be removed, if possible
        :return True if removal was successful, False otherwise
        """
        pass

    @abc.abstractmethod
    def push(self, entry):
        """Adds an entry to the top of the stack
        :post The entry will be added to the top of the stack, if possible
        :return True if addition was successful, False otherwise
        """
        pass

An abstract base class (which is what the interface here is) cannot be instantiated, hence the word abstract. Go ahead and try, I did. The result was

TypeError: Can't instantiate abstract class StackInterface with abstract methods is_empty, peek, pop, push

This is good because we’ve described a stack as a data structure that has these methods. Any class that subclasses the StackInterface class must implement these methods and therefore live up to the specification that we wrote. If these methods haven’t been implemented, then the specifications have not been met and the subclass can’t be instantiated. Neat!

Conclusion

In this article we talked about what a stack is, what a linked stack is, and then we wrote an interface for a stack. In the next article, we’ll start implementing the linked stack by implementing the push method.

References

1. Stack (Abstract Data Type)
2. How Are Lists Implemented in CPython?
3. Linked Data Structure
4. Data Abstraction & Problem Solving with C++: Walls and Mirrors, 6th Edition
5. Starting out with C++: From Control Structure Through Objects, 8th Edition
6. PyMOTW 3: abc — Abstract Base Classes
7. Interfaces - The Most Important Software Engineering Concept

Resources

1. Stack of dirty dishes. Image courtesy of torange.biz, License CC-BY 4.0
2. A block of memory representing an array. Image courtesy of Jarkko Piiroinen