Get to your ebooks quickly

So this is going to be a little longer post than usual.

To begin with, here is screenshot of how it would look like finally:

We are using “rofi” here to show the menu. So, lets first install that

cat <<EOF >/etc/yum.repos.d/_copr_yaroslav-i3desktop.repo 
[yaroslav-i3desktop]
name=Copr repo for i3desktop owned by yaroslav
baseurl=https://copr-be.cloud.fedoraproject.org/results/yaroslav/i3desktop/fedora-$releasever-$basearch/
type=rpm-md
skip_if_unavailable=True
gpgcheck=1
gpgkey=https://copr-be.cloud.fedoraproject.org/results/yaroslav/i3desktop/pubkey.gpg
repo_gpgcheck=0
enabled=1
EOF

yum install rofi
Once that is done, we will create a small script to look for all our pdf files and display that in the menu, like above. Save this as ~/bin/books-search.sh :
 
#!/usr/bin/env bash
#
# wget 'https://raw.githubusercontent.com/miroslavvidovic/rofi-scripts/master/books-search/books-search.sh'

# -----------------------------------------------------------------------------
# Info:
#   author:    Miroslav Vidovic
#   file:      books-search.sh
#   created:   13.08.2017.-08:06:54
#   revision:  ---
#   version:   1.0
# -----------------------------------------------------------------------------
# Requirements:
#   rofi
# Description:
#   Use rofi to search my books.
# Usage:
#   books-search.sh
# -----------------------------------------------------------------------------
# Script:
# Modified by Amit Agarwal

# Books directory
BOOKS_DIR=/usr/share/texlive/texmf-dist/doc/

# Save find result to F_ARRAY
readarray -t F_ARRAY <<< "$(find "$BOOKS_DIR" -type f -name '*.pdf')"

# Associative array for storing books
# key => book name
# value => absolute path to the file
# BOOKS['filename']='path'
declare -A BOOKS

# Add elements to BOOKS array
get_books() {
    for i in "${!F_ARRAY[@]}"
    do
        path=${F_ARRAY[$i]}
        file=$(basename "${F_ARRAY[$i]}")
        BOOKS+=(["$file"]="$path")
    done
}

# List for rofi
gen_list(){
    for i in "${!BOOKS[@]}"
    do
      echo "$i"
    done
}

main() {
  get_books
  #
 book=$( (gen_list) | rofi -dmenu -lines 10 -width 100 -i -matching 
fuzzy -only-match -location 0 -fake-transparency -p "Book > " )
  book=$( (gen_list) | rofi -dmenu -i -matching fuzzy -only-match -p "Book > " )
  xdg-open "${BOOKS[$book]}"
}

main
exit 0
In the above script, change the BOOKS_DIR to the one that you would like to see. And finally make some cosmetic changes:
cat <<EOF >~/.Xresources 
rofi.color-enabled: true
rofi.opacity:                        50
rofi.width:                          100
rofi.lines:                          10
rofi.columns:                        4
rofi.font:                           System San Francisco Display 8
rofi.color-normal:                   #fdf6e3,#002b36,#eee8d5,#586e75,#eee8d5
rofi.color-urgent:                   #fdf6e3,#dc322f,#eee8d5,#dc322f,#fdf6e3
rofi.color-active:                   #fdf6e3,#268bd2,#eee8d5,#268bd2,#fdf6e3
rofi.color-window:                   #fdf6e3,#002b36
rofi.yoffset:                        0
rofi.xoffset:                        0
rofi.fixed-num-lines:                false
rofi.terminal:                       rofi-sensible-terminal
rofi.ssh-client:                     ssh
rofi.ssh-command:                    {terminal} -e {ssh-client} {host}
rofi.run-command:                    {cmd}
rofi.run-list-command:               
rofi.run-shell-command:              {terminal} -e {cmd}
rofi.window-command:                 xkill -id {window}
rofi.disable-history:                false
rofi.levenshtein-sort:               false
rofi.case-sensitive:                 false
rofi.cycle:                          true
rofi.sidebar-mode:                   false
rofi.auto-select:                    false
rofi.parse-hosts:                    true
rofi.parse-known-hosts:              true
rofi.combi-modi:                     window,run
rofi.fuzzy:                          true
rofi.glob:                           false
rofi.regex:                          false
rofi.tokenize:                       true
rofi.m:                              -1
rofi.line-margin:                    2
rofi.filter:                         
rofi.separator-style:                dash
rofi.hide-scrollbar:                 false
rofi.fullscreen:                     false
rofi.fake-transparency:              true
rofi.dpi:                            -1
rofi.threads:                        1
rofi.scrollbar-width:                8
rofi.scroll-method:                  0
rofi.fake-background:                screenshot
rofi.display-ssh:                    
rofi.display-run:                    
rofi.display-drun:                   
rofi.display-combi:
EOF


xrdb -merge ~/.Xresources
Finally for easy access, you might want to bind a key to lauch the script that we created and voila.

Styled-Components: CSS-in-JS Library for the Modern Web

This post was written by Jeremy Davis, JavaScript Developer for Toptal.

 

CSS was designed for documents, what the “old web” was expected to contain. The emergence of preprocessors like Sass or Less shows that the community needs more than what CSS offers. With web apps getting more and more complex over time, CSS’ limitations have become increasingly visible and difficult to mitigate.

Styled-components leverages the power of a complete programming language—JavaScript—and its scoping capabilities to help structure the code into components. This helps to avoid the common pitfalls of writing and maintaining CSS for large projects. A developer can describe a component’s style with no risk of side effects.

What’s the Problem?

One advantage of using CSS is that the style is completely decoupled from the code. This means that developers and designers can work in parallel without interfering with each other.

On the other hand, styled-components makes it easier to fall in the trap of strongly coupling style and logic. Max Stoiber explains how to avoid this. While the idea of separating logic and presentation is definitely not new, one might be tempted to take shortcuts when developing React components. For example, it’s easy to create a component for a validation button that handles the click action as well as the button’s style. It takes a bit more effort to split it in two components.

The Container/Presentational Architecture

This is a pretty simple principle. Components either define how things look, or they manage data and logic. A very important aspect of presentation components is that they should never have any dependencies. They receive props and render DOM (or children) accordingly. Containers, on the other hand, know about the data architecture (state, redux, flux, etc.) but should never be responsible for display. Dan Abramov’s article is a very good and detailed explanation of this architecture.

Remembering SMACSS

Although the Scalable and Modular Architecture for CSS is a style guide for organizing CSS, the basic concept is one that is followed, for the most part automatically, by styled-components. The idea is to separate CSS into five categories:

  • Base contains all the general rules.
  • Layout’s purpose it to define the structural properties as well as various sections of content (header, footer, sidebar, content, for instance).
  • Module contains subcategories for the various logical blocks of the UI.
  • State defines modifier classes to indicate elements’ states, e.g. field in error, disabled button.
  • Theme contains color, font, and other cosmetic aspects that may be modifiable or dependent on user preference.

Keeping this separation while using styled-components is easy. Projects usually include some kind of CSS normalization or reset. This typically falls in the Base category. You may also define general font sizing, line sizing, etc. This can be done through normal CSS (or Sass/Less), or through the 

1
injectGlobal

 function provided by styled-components.

For Layout rules, if you use a UI framework, then it will probably define container classes, or a grid system. You can easily use those classes in conjunction with your own rules in the layout components you write.

Module is automatically followed by the architecture of styled-components, since the styles are attached to components directly, rather than described in external files. Basically, each styled component that you write will be its own module. You can write your styling code without worrying about side effects.

State will be rules you define within your components as variable rules. You simply define a function to interpolate values of your CSS attributes. If using a UI framework, you might have useful classes to add to your components as well. You will probably also have CSS pseudo-selector rules (hover, focus, etc.)

The Theme can simply be interpolated within your components. It is a good idea to define your theme as a set of variables to be used throughout your application. You can even derive colors programmatically (using a library, or manually), for instance to handle contrasts and highlights. Remember that you have the full power of a programming language at your disposal!

Bring Them Together for a Solution

It is important to keep them together, for an easier navigation experience; We don’t want to organize them by type (presentation vs. logic) but rather by functionality.

Thus, we will have a folder for all the generic components (buttons and such). The others should be organized depending on the project and its functionalities. For instance, if we have user management features, we should group all the components specific to that feature.

To apply styled-components’ container/presentation architecture to a SMACSS approach, we need an extra type of component: structural. We end up with three kinds of components; styled, structural, and container. Since styled-components decorates a tag (or component), we need this third type of component to structure the DOM. In some cases, it might be possible to allow a container component to handle the structure of sub-components, but when the DOM structure becomes complex and is required for visual purposes, it’s best to separate them. A good example is a table, where the DOM typically gets quite verbose.

Example Project

Let’s build a small app that displays recipes to illustrate these principles. We can start building a Recipes component. The parent component will be a controller. It will handle the state—in this case, the list of recipes. It will also call an API function to fetch the data.


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
<span class="hljs-class"><span class="hljs-keyword">class</span> <span class="hljs-title">Recipes</span> <span class="hljs-keyword">extends</span> <span class="hljs-title">Component</span></span>{
  <span class="hljs-keyword">constructor</span> (props) {
    <span class="hljs-keyword">super</span>(props);
    <span class="hljs-keyword">this</span>.state = {
      <span class="hljs-attr">recipes</span>: []
    };
  }

  componentDidMount () {
    <span class="hljs-keyword">this</span>.loadData()
  }

  loadData () {
    getRecipes().then(<span class="hljs-function"><span class="hljs-params">recipes</span> =&gt;</span> {
      <span class="hljs-keyword">this</span>.setState({recipes})
    })
  }

  render() {
    <span class="hljs-keyword">let</span> {recipes} = <span class="hljs-keyword">this</span>.state

    <span class="hljs-keyword">return</span> (
      <span class="xml"><span class="hljs-tag">&lt;<span class="hljs-name">RecipesContainer</span> <span class="hljs-attr">recipes</span>=<span class="hljs-string">{recipes}</span> /&gt;</span>
    )
  }
}
</span>

It will render the list of recipes, but it does not (and should not) need to know how. So we render another component that gets the list of recipes and outputs DOM:


1
2
3
4
5
6
7
8
9
10
11
12
<span class="hljs-class"><span class="hljs-keyword">class</span> <span class="hljs-title">RecipesContainer</span> <span class="hljs-keyword">extends</span> <span class="hljs-title">Component</span></span>{
  render() {
    <span class="hljs-keyword">let</span> {recipes} = <span class="hljs-keyword">this</span>.props

    <span class="hljs-keyword">return</span> (
      <span class="xml"><span class="hljs-tag">&lt;<span class="hljs-name">TilesContainer</span>&gt;</span>
        {recipes.map(recipe =&gt; (<span class="hljs-tag">&lt;<span class="hljs-name">Recipe</span> <span class="hljs-attr">key</span>=<span class="hljs-string">{recipe.id}</span> {<span class="hljs-attr">...recipe</span>}/&gt;</span>))}
      <span class="hljs-tag">&lt;/<span class="hljs-name">TilesContainer</span>&gt;</span>
    )
  }
}
</span>

Here, actually, we want to make a tile grid. It may be a good idea to make the actual tile layout a generic component. So if we extract that, we get a new component that looks like this:


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
<span class="hljs-class"><span class="hljs-keyword">class</span> <span class="hljs-title">TilesContainer</span> <span class="hljs-keyword">extends</span> <span class="hljs-title">Component</span> </span>{
  render () {
    <span class="hljs-keyword">let</span> {children} = <span class="hljs-keyword">this</span>.props

    <span class="hljs-keyword">return</span> (
      <span class="xml"><span class="hljs-tag">&lt;<span class="hljs-name">Tiles</span>&gt;</span>
        {
          React.Children.map(children, (child, i) =&gt; (
            <span class="hljs-tag">&lt;<span class="hljs-name">Tile</span> <span class="hljs-attr">key</span>=<span class="hljs-string">{i}</span>&gt;</span>
              {child}
            <span class="hljs-tag">&lt;/<span class="hljs-name">Tile</span>&gt;</span>
          ))
        }
      <span class="hljs-tag">&lt;/<span class="hljs-name">Tiles</span>&gt;</span></span>
    )
  }
}

TilesStyles.js:


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
<span class="hljs-keyword">export</span> <span class="hljs-keyword">const</span> Tiles = styled.div<span class="hljs-string">`
  padding: 20px 10px;
  display: flex;
  flex-direction: row;
  flex-wrap: wrap;
`</span>

<span class="hljs-keyword">export</span> <span class="hljs-keyword">const</span> Tile = styled.div<span class="hljs-string">`
  flex: 1 1 auto;
  ...
  display: flex;

  &amp; &gt; div {
    flex: 1 0 auto;
  }
`</span>

Notice that this component is purely presentational. It defines its style and wraps whatever children it receives inside another styled DOM element that defines what tiles look like. It’s a good example of what your generic presentational components will look like architecturally.

Then, we need to define what a recipe looks like. We need a container component to describe the relatively complex DOM as well as define the style when necessary. We end up with this:


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
<span class="hljs-class"><span class="hljs-keyword">class</span> <span class="hljs-title">RecipeContainer</span> <span class="hljs-keyword">extends</span> <span class="hljs-title">Component</span> </span>{
  onChangeServings (e) {
    <span class="hljs-keyword">let</span> {changeServings} = <span class="hljs-keyword">this</span>.props
    changeServings(e.target.value)
  }

  render () {
    <span class="hljs-keyword">let</span> {title, ingredients, instructions, time, servings} = <span class="hljs-keyword">this</span>.props

    <span class="hljs-keyword">return</span> (
      <span class="xml"><span class="hljs-tag">&lt;<span class="hljs-name">Recipe</span>&gt;</span>
        <span class="hljs-tag">&lt;<span class="hljs-name">Title</span>&gt;</span>{title}<span class="hljs-tag">&lt;/<span class="hljs-name">Title</span>&gt;</span>
        <span class="hljs-tag">&lt;<span class="hljs-name">div</span>&gt;</span>{time}<span class="hljs-tag">&lt;/<span class="hljs-name">div</span>&gt;</span>
        <span class="hljs-tag">&lt;<span class="hljs-name">div</span>&gt;</span>Serving
          <span class="hljs-tag">&lt;<span class="hljs-name">input</span> <span class="hljs-attr">type</span>=<span class="hljs-string">"number"</span> <span class="hljs-attr">min</span>=<span class="hljs-string">"1"</span> <span class="hljs-attr">max</span>=<span class="hljs-string">"1000"</span> <span class="hljs-attr">value</span>=<span class="hljs-string">{servings}</span> <span class="hljs-attr">onChange</span>=<span class="hljs-string">{this.onChangeServings.bind(this)}/</span>&gt;</span>
        <span class="hljs-tag">&lt;/<span class="hljs-name">div</span>&gt;</span>
        <span class="hljs-tag">&lt;<span class="hljs-name">Ingredients</span>&gt;</span>
          {ingredients.map((ingredient, i) =&gt; (
            <span class="hljs-tag">&lt;<span class="hljs-name">Ingredient</span> <span class="hljs-attr">key</span>=<span class="hljs-string">{i}</span> <span class="hljs-attr">servings</span>=<span class="hljs-string">{servings}</span>&gt;</span>
              <span class="hljs-tag">&lt;<span class="hljs-name">span</span> <span class="hljs-attr">className</span>=<span class="hljs-string">"name"</span>&gt;</span>{ingredient.name}<span class="hljs-tag">&lt;/<span class="hljs-name">span</span>&gt;</span>
              <span class="hljs-tag">&lt;<span class="hljs-name">span</span> <span class="hljs-attr">className</span>=<span class="hljs-string">"quantity"</span>&gt;</span>{ingredient.quantity * servings} {ingredient.unit}<span class="hljs-tag">&lt;/<span class="hljs-name">span</span>&gt;</span>
            <span class="hljs-tag">&lt;/<span class="hljs-name">Ingredient</span>&gt;</span>
          ))}
        <span class="hljs-tag">&lt;/<span class="hljs-name">Ingredients</span>&gt;</span>
        <span class="hljs-tag">&lt;<span class="hljs-name">div</span>&gt;</span>
          {instructions.map((instruction, i) =&gt; (<span class="hljs-tag">&lt;<span class="hljs-name">p</span> <span class="hljs-attr">key</span>=<span class="hljs-string">{i}</span>&gt;</span>{instruction}<span class="hljs-tag">&lt;/<span class="hljs-name">p</span>&gt;</span>))}
        <span class="hljs-tag">&lt;/<span class="hljs-name">div</span>&gt;</span>
      <span class="hljs-tag">&lt;/<span class="hljs-name">Recipe</span>&gt;</span>
    )
  }
}
</span>

Notice here that the container does some DOM generation, but it’s the only logic it contains. Remember that you can define nested styles, so you don’t need to make a styled element for each tag that requires styling. It’s what we do here for the name and quantity of the ingredient item. Of course, we could split it further and create a new component for an ingredient. That is up to you—depending on the project complexity—to determine the granularity. In this case, it is just a styled component defined along with the rest in the RecipeStyles file:


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
<span class="hljs-keyword">export</span> <span class="hljs-keyword">const</span> Recipe = styled.div<span class="hljs-string">`
  background-color: <span class="hljs-subst">${theme('colors.background-highlight')}</span>;
`</span>;

<span class="hljs-keyword">export</span> <span class="hljs-keyword">const</span> Title = styled.div<span class="hljs-string">`
  font-weight: bold;
`</span>

<span class="hljs-keyword">export</span> <span class="hljs-keyword">const</span> Ingredients = styled.ul<span class="hljs-string">`
  margin: 5px 0;
`</span>

<span class="hljs-keyword">export</span> <span class="hljs-keyword">const</span> Ingredient = styled.li<span class="hljs-string">`
  &amp; .name {
    ...
  }

  &amp; .quantity {
    ...
  }
`</span>

For the purpose of this exercise, I have used the ThemeProvider. It injects the theme in the props of styled components. You can simply use it as 

1
color: ${props =&gt; props.theme.core_color}

, I am just using a small wrapper to protect from missing attributes in the theme:


1
<span class="hljs-keyword">const</span> theme = <span class="hljs-function">(<span class="hljs-params">key</span>) =&gt;</span> (prop) =&gt; _.get(prop.theme, key) || <span class="hljs-built_in">console</span>.warn(<span class="hljs-string">'missing key'</span>, key)

You can also define your own constants in a module and use those instead. For example: 

1
color: ${styleConstants.core_color}

Pros

A perk of using styled-components is that you can use it as little as you want. You can use your favorite UI framework and add styled-components on top of it. This also means that you can easily migrate an existing project component by component. You can choose to style most of the layout with standard CSS and only use styled-components for reusable components.

Cons

Designers/style integrators will need to learn very basic JavaScript to handle variables and use them in place of Sass/Less.

They will also have to learn to navigate the project structure, although I would argue that finding the styles for a component in that component’s folder is easier than having to find the right CSS/Sass/Less file that contains the rule you need to modify.

They will also need to change their tools a bit if they want syntax highlighting, linting, etc. A good place to start is with this Atom plugin and this babel plugin.

Python Class Attributes: An Overly Thorough Guide

This article is originally published at Toptal.

I had a programming interview recently, a phone-screen in which we used a collaborative text editor.

I was asked to implement a certain API, and chose to do so in Python. Abstracting away the problem statement, let’s say I needed a class whose instances stored some 

1
data

 and some 

1
other_data

.

I took a deep breath and started typing. After a few lines, I had something like this:


1
2
3
4
5
6
class Service(object):
    data = []

    def __init__(self, other_data):
        self.other_data = other_data
    ...

My interviewer stopped me:

  • Interviewer: “That line: 
    1
    data = []

    . I don’t think that’s valid Python?”

  • Me: “I’m pretty sure it is. It’s just setting a default value for the instance attribute.”
  • Interviewer: “When does that code get executed?”
  • Me: “I’m not really sure. I’ll just fix it up to avoid confusion.”

For reference, and to give you an idea of what I was going for, here’s how I amended the code:


1
2
3
4
5
6
class Service(object):

    def __init__(self, other_data):
        self.data = []
        self.other_data = other_data
    ...

As it turns out, we were both wrong. The real answer lay in understanding the distinction between Python class attributes and Python instance attributes.

Python class attributes vs. Python instance attributes

Note: if you have an expert handle on class attributes, you can skip ahead to use cases.

Python Class Attributes

My interviewer was wrong in that the above code is syntactically valid.

I too was wrong in that it isn’t setting a “default value” for the instance attribute. Instead, it’s defining 

1
data

 as a class attribute with value 

1
[]

.

In my experience, Python class attributes are a topic that many people know something about, but few understand completely.

Python Class Variable vs. Instance Variable: What’s the Difference?

A Python class attribute is an attribute of the class (circular, I know), rather than an attribute of an instance of a class.

Let’s use a Python class example to illustrate the difference. Here, 

1
class_var

 is a class attribute, and 

1
i_var

 is an instance attribute:


1
2
3
4
5
class MyClass(object):
    class_var = 1

    def __init__(self, i_var):
        self.i_var = i_var

Note that all instances of the class have access to 

1
class_var

, and that it can also be accessed as a property of the class itself:


1
2
3
4
5
6
7
8
9
foo = MyClass(2)
bar = MyClass(3)

foo.class_var, foo.i_var
## 1, 2
bar.class_var, bar.i_var
## 1, 3
MyClass.class_var ## &lt;— This is key
## 1

For Java or C++ programmers, the class attribute is similar—but not identical—to the static member. We’ll see how they differ later.

Class vs. Instance Namespaces

To understand what’s happening here, let’s talk briefly about Python namespaces.

namespace is a mapping from names to objects, with the property that there is zero relation between names in different namespaces. They’re usually implemented as Python dictionaries, although this is abstracted away.

Depending on the context, you may need to access a namespace using dot syntax (e.g., 

1
object.name_from_objects_namespace

) or as a local variable (e.g., 

1
object_from_namespace

). As a concrete example:


1
2
3
4
5
6
7
8
9
10
class MyClass(object):
    ## No need for dot syntax
    class_var = 1

    def __init__(self, i_var):
        self.i_var = i_var

## Need dot syntax as we've left scope of class namespace
MyClass.class_var
## 1

Python classes and instances of classes each have their own distinct namespaces represented by pre-defined attributes 

1
MyClass.__dict__

 and 

1
 

, respectively.

When you try to access an attribute from an instance of a class, it first looks at its instance namespace. If it finds the attribute, it returns the associated value. If not, it then looks in the class namespace and returns the attribute (if it’s present, throwing an error otherwise). For example:


1
2
3
4
5
6
7
8
9
10
foo = MyClass(2)

## Finds i_var in foo's instance namespace
foo.i_var
## 2

## Doesn't find class_var in instance namespace…
## So look's in class namespace (MyClass.__dict__)
foo.class_var
## 1

The instance namespace takes supremacy over the class namespace: if there is an attribute with the same name in both, the instance namespace will be checked first and its value returned. Here’s a simplified version of the code (source) for attribute lookup:


1
2
3
4
5
6
def instlookup(inst, name):
    ## simplified algorithm...
    if inst.__dict__.has_key(name):
        return inst.__dict__[name]
    else:
        return inst.__class__.__dict__[name]

And, in visual form:

attribute lookup in visual form

How Class Attributes Handle Assignment

With this in mind, we can make sense of how Python class attributes handle assignment:

  • If a class attribute is set by accessing the class, it will override the value for all instances. For example:
    
    
    1
    2
    3
    4
    5
    6
    foo = MyClass(2)
    foo.class_var
    ## 1
    MyClass.class_var = 2
    foo.class_var
    ## 2

    At the namespace level… we’re setting 

    1
    MyClass.__dict__['class_var'] = 2

    . (Note: this isn’t the exact code(which would be 

    1
    setattr(MyClass, 'class_var', 2)

    ) as 

    1
    __dict__

     returns a dictproxy, an immutable wrapper that prevents direct assignment, but it helps for demonstration’s sake). Then, when we access 

    1
    foo.class_var

    1
    class_var

     has a new value in the class namespace and thus 2 is returned.

  • If a Paython class variable is set by accessing an instance, it will override the value only for that instance. This essentially overrides the class variable and turns it into an instance variable available, intuitively, only for that instance. For example:
    
    
    1
    2
    3
    4
    5
    6
    7
    8
    foo = MyClass(2)
    foo.class_var
    ## 1
    foo.class_var = 2
    foo.class_var
    ## 2
    MyClass.class_var
    ## 1

    At the namespace level… we’re adding the 

    1
    class_var

     attribute to 

    1
    foo.__dict__

    , so when we lookup 

    1
    foo.class_var

    , we return 2. Meanwhile, other instances of 

    1
    MyClass

     will not have 

    1
    class_var

     in their instance namespaces, so they continue to find 

    1
    class_var

     in 

    1
    MyClass.__dict__

     and thus return 1.

Mutability

Quiz question: What if your class attribute has a mutable type? You can manipulate (mutilate?) the class attribute by accessing it through a particular instance and, in turn, end up manipulating the referenced object that all instances are accessing (as pointed out by Timothy Wiseman).

This is best demonstrated by example. Let’s go back to the 

1
Service

 I defined earlier and see how my use of a class variable could have led to problems down the road.


1
2
3
4
5
6
class Service(object):
    data = []

    def __init__(self, other_data):
        self.other_data = other_data
    ...

My goal was to have the empty list (

1
[]

) as the default value for 

1
data

, and for each instance of 

1
Service

 to have its own data that would be altered over time on an instance-by-instance basis. But in this case, we get the following behavior (recall that 

1
Service

 takes some argument 

1
other_data

, which is arbitrary in this example):


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
s1 = Service(['a', 'b'])
s2 = Service(['c', 'd'])

s1.data.append(1)

s1.data
## [1]
s2.data
## [1]

s2.data.append(2)

s1.data
## [1, 2]
s2.data
## [1, 2]

This is no good—altering the class variable via one instance alters it for all the others!

At the namespace level… all instances of 

1
Service

 are accessing and modifying the same list in 

1
Service.__dict__

 without making their own 

1
data

 attributes in their instance namespaces.

We could get around this using assignment; that is, instead of exploiting the list’s mutability, we could assign our 

1
Service

 objects to have their own lists, as follows:


1
2
3
4
5
6
7
8
9
10
s1 = Service(['a', 'b'])
s2 = Service(['c', 'd'])

s1.data = [1]
s2.data = [2]

s1.data
## [1]
s2.data
## [2]

In this case, we’re adding 

1
s1.__dict__['data'] = [1]

, so the original 

1
Service.__dict__['data']

 remains unchanged.

Unfortunately, this requires that 

1
Service

 users have intimate knowledge of its variables, and is certainly prone to mistakes. In a sense, we’d be addressing the symptoms rather than the cause. We’d prefer something that was correct by construction.

My personal solution: if you’re just using a class variable to assign a default value to a would-be Python instance variable, don’t use mutable values. In this case, every instance of 

1
Service

 was going to override 

1
Service.data

 with its own instance attribute eventually, so using an empty list as the default led to a tiny bug that was easily overlooked. Instead of the above, we could’ve either:

  1. Stuck to instance attributes entirely, as demonstrated in the introduction.
  2. Avoided using the empty list (a mutable value) as our “default”:
    
    
    1
    2
    3
    4
    5
    6
    class Service(object):
        data = None

        def __init__(self, other_data):
            self.other_data = other_data
        ...

    Of course, we’d have to handle the 

    1
    None

     case appropriately, but that’s a small price to pay.

So When Should you Use Python Class Attributes?

Class attributes are tricky, but let’s look at a few cases when they would come in handy:

  1. Storing constants. As class attributes can be accessed as attributes of the class itself, it’s often nice to use them for storing Class-wide, Class-specific constants. For example:
    
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    class Circle(object):
        pi = 3.14159

        def __init__(self, radius):
            self.radius = radius

        def area(self):
            return Circle.pi * self.radius * self.radius

    Circle.pi
    ## 3.14159

    c = Circle(10)
    c.pi
    ## 3.14159
    c.area()
    ## 314.159
  2. Defining default values. As a trivial example, we might create a bounded list (i.e., a list that can only hold a certain number of elements or fewer) and choose to have a default cap of 10 items:
    
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    class MyClass(object):
        limit = 10

        def __init__(self):
            self.data = []

        def item(self, i):
            return self.data[i]

        def add(self, e):
            if len(self.data) &gt;= self.limit:
                raise Exception("Too many elements")
            self.data.append(e)

    MyClass.limit
    ## 10

    We could then create instances with their own specific limits, too, by assigning to the instance’s 

    1
    limit

    attribute.

    
    
    1
    2
    3
    foo = MyClass()
    foo.limit = 50
    ## foo can now hold 50 elements—other instances can hold 10

    This only makes sense if you will want your typical instance of 

    1
    MyClass

     to hold just 10 elements or fewer—if you’re giving all of your instances different limits, then 

    1
    limit

     should be an instance variable. (Remember, though: take care when using mutable values as your defaults.)

  3. Tracking all data across all instances of a given class. This is sort of specific, but I could see a scenario in which you might want to access a piece of data related to every existing instance of a given class.To make the scenario more concrete, let’s say we have a 
    1
    Person

     class, and every person has a 

    1
    name

    . We want to keep track of all the names that have been used. One approach might be to iterate over the garbage collector’s list of objects, but it’s simpler to use class variables.

    Note that, in this case, 

    1
    names

     will only be accessed as a class variable, so the mutable default is acceptable.

    
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    class Person(object):
        all_names = []

        def __init__(self, name):
            self.name = name
            Person.all_names.append(name)

    joe = Person('Joe')
    bob = Person('Bob')
    print Person.all_names
    ## ['Joe', 'Bob']

    We could even use this design pattern to track all existing instances of a given class, rather than just some associated data.

    
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    class Person(object):
        all_people = []

        def __init__(self, name):
            self.name = name
            Person.all_people.append(self)

    joe = Person('Joe')
    bob = Person('Bob')
    print Person.all_people
    ## [&lt;__main__.Person object at 0x10e428c50&gt;, &lt;__main__.Person object at 0x10e428c90&gt;]
  4. Performance (sort of… see below).

Under-the-hood

Note: If you’re worrying about performance at this level, you might not want to be use Python in the first place, as the differences will be on the order of tenths of a millisecond—but it’s still fun to poke around a bit, and helps for illustration’s sake.

Recall that a class’s namespace is created and filled in at the time of the class’s definition. That means that we do just one assignment—ever—for a given class variable, while instance variables must be assigned every time a new instance is created. Let’s take an example.


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
def called_class():
    print "Class assignment"
    return 2

class Bar(object):
    y = called_class()

    def __init__(self, x):
        self.x = x

## "Class assignment"

def called_instance():
    print "Instance assignment"
    return 2

class Foo(object):
    def __init__(self, x):
        self.y = called_instance()
        self.x = x

Bar(1)
Bar(2)
Foo(1)
## "Instance assignment"
Foo(2)
## "Instance assignment"

We assign to 

1
Bar.y

 just once, but 

1
instance_of_Foo.y

 on every call to 

1
__init__

.

As further evidence, let’s use the Python disassembler:


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
import dis

class Bar(object):
    y = 2

    def __init__(self, x):
        self.x = x

class Foo(object):
    def __init__(self, x):
        self.y = 2
        self.x = x

dis.dis(Bar)
##  Disassembly of __init__:
##  7           0 LOAD_FAST                1 (x)
##              3 LOAD_FAST                0 (self)
##              6 STORE_ATTR               0 (x)
##              9 LOAD_CONST               0 (None)
##             12 RETURN_VALUE

dis.dis(Foo)
## Disassembly of __init__:
## 11           0 LOAD_CONST               1 (2)
##              3 LOAD_FAST                0 (self)
##              6 STORE_ATTR               0 (y)

## 12           9 LOAD_FAST                1 (x)
##             12 LOAD_FAST                0 (self)
##             15 STORE_ATTR               1 (x)
##             18 LOAD_CONST               0 (None)
##             21 RETURN_VALUE

When we look at the byte code, it’s again obvious that 

1
Foo.__init__

 has to do two assignments, while 

1
Bar.__init__

 does just one.

In practice, what does this gain really look like? I’ll be the first to admit that timing tests are highly dependent on often uncontrollable factors and the differences between them are often hard to explain accurately.

However, I think these small snippets (run with the Python timeit module) help to illustrate the differences between class and instance variables, so I’ve included them anyway.

Note: I’m on a MacBook Pro with OS X 10.8.5 and Python 2.7.2.

Initialization


1
2
10000000 calls to `Bar(2)`: 4.940s
10000000 calls to `Foo(2)`: 6.043s

The initializations of 

1
Bar

 are faster by over a second, so the difference here does appear to be statistically significant.

So why is this the case? One speculative explanation: we do two assignments in 

1
Foo.__init__

, but just one in 

1
Bar.__init__

.

Assignment


1
2
3
4
10000000 calls to `Bar(2).y = 15`: 6.232s
10000000 calls to `Foo(2).y = 15`: 6.855s
10000000 `Bar` assignments: 6.232s - 4.940s = 1.292s
10000000 `Foo` assignments: 6.855s - 6.043s = 0.812s

Note: There’s no way to re-run your setup code on each trial with timeit, so we have to reinitialize our variable on our trial. The second line of times represents the above times with the previously calculated initialization times deducted.

From the above, it looks like 

1
Foo

 only takes about 60% as long as 

1
Bar

 to handle assignments.

Why is this the case? One speculative explanation: when we assign to 

1
Bar(2).y

, we first look in the instance namespace (

1
Bar(2).__dict__[y]

), fail to find 

1
y

, and then look in the class namespace (

1
Bar.__dict__[y]

), then making the proper assignment. When we assign to 

1
Foo(2).y

, we do half as many lookups, as we immediately assign to the instance namespace (

1
Foo(2).__dict__[y]

).

In summary, though these performance gains won’t matter in reality, these tests are interesting at the conceptual level. If anything, I hope these differences help illustrate the mechanical distinctions between class and instance variables.

In Conclusion

Class attributes seem to be underused in Python; a lot of programmers have different impressions of how they work and why they might be helpful.

My take: Python class variables have their place within the school of good code. When used with care, they can simplify things and improve readability. But when carelessly thrown into a given class, they’re sure to trip you up.

Appendix: Private Instance Variables

One thing I wanted to include but didn’t have a natural entrance point…

Python doesn’t have private variables so-to-speak, but another interesting relationship between class and instance naming comes with name mangling.

In the Python style guide, it’s said that pseudo-private variables should be prefixed with a double underscore: ‘__’. This is not only a sign to others that your variable is meant to be treated privately, but also a way to prevent access to it, of sorts. Here’s what I mean:


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
class Bar(object):
    def __init__(self):
    self.__zap = 1

a = Bar()
a.__zap
## Traceback (most recent call last):
##   File "&lt;stdin&gt;", line 1, in &lt;module&gt;
## AttributeError: 'Bar' object has no attribute '__baz'

## Hmm. So what's in the namespace?
a.__dict__
{'_Bar__zap': 1}
a._Bar__zap
## 1

Look at that: the instance attribute 

1
__zap

 is automatically prefixed with the class name to yield 

1
_Bar__zap

.

While still settable and gettable using 

1
a._Bar__zap

, this name mangling is a means of creating a ‘private’ variable as it prevents you and others from accessing it by accident or through ignorance.

Edit: as Pedro Werneck kindly pointed out, this behavior is largely intended to help out with subclassing. In the PEP 8 style guide, they see it as serving two purposes: (1) preventing subclasses from accessing certain attributes, and (2) preventing namespace clashes in these subclasses. While useful, variable mangling shouldn’t be seen as an invitation to write code with an assumed public-private distinction, such as is present in Java.