Keywords: ext

## 2.2.2 Object Representation

In Python, there are three ways to generate a textual representation of an object: the `repr()` function (or equivalent backtick syntax), the `str()` function, and the `print` statement. For most objects, the `print` statement is equivalent to the `str()` function, but it is possible to special-case printing to a `FILE*` if necessary; this should only be done if efficiency is identified as a problem and profiling suggests that creating a temporary string object to be written to a file is too expensive.

These handlers are all optional, and most types at most need to implement the `tp_str` and `tp_repr` handlers.

          reprfunc tp_repr;
          reprfunc tp_str;
          printfunc tp_print;

The `tp_repr` handler should return a string object containing a representation of the instance for which it is called. Here is a simple example:

      static PyObject *
      newdatatype_repr(newdatatypeobject * obj)
      {
          return PyString_FromFormat("Repr-ified_newdatatype{{size:\%d}}",
                  obj->obj_UnderlyingDatatypePtr->size);
      }

If no `tp_repr` handler is specified, the interpreter will supply a representation that uses the type's `tp_name` and a uniquely-identifying value for the object.

The `tp_str` handler is to `str()` what the `tp_repr` handler described above is to `repr()`; that is, it is called when Python code calls `str()` on an instance of your object. It's implementation is very similar to the `tp_repr` function, but the resulting string is intended for human consumption. It `tp_str` is not specified, the `tp_repr` handler is used instead.

Here is a simple example:

      static PyObject *
      newdatatype_str(newdatatypeobject * obj)
      {
          return PyString_FromFormat("Stringified_newdatatype{{size:\%d}}",
              obj->obj_UnderlyingDatatypePtr->size
              );
      }

The print function will be called whenever Python needs to "print" an instance of the type. For example, if 'node' is an instance of type TreeNode, then the print function is called when Python code calls:

      print node

There is a flags argument and one flag, `Py_PRINT_RAW`, and it suggests that you print without string quotes and possibly without interpreting escape sequences.

The print function receives a file object as an argument. You will likely want to write to that file object.

Here is a sampe print function:

      static int
      newdatatype_print(newdatatypeobject *obj, FILE *fp, int flags)
      {
          if (flags & Py_PRINT_RAW) {
              fprintf(fp, "<{newdatatype object--size: %d}>",
                      obj->obj_UnderlyingDatatypePtr->size);
          }
          else {
              fprintf(fp, "\"<{newdatatype object--size: %d}>\"",
                      obj->obj_UnderlyingDatatypePtr->size);
          }
          return 0;
      }