Merge pull request #289 from jagerman/example-renaming

Rename examples files, as per #288

docs/advanced.rst

@@ -102,8 +102,9 @@ C++ side, or to perform other types of customization.
 
 .. seealso::
 
-    The file :file:`example/example3.cpp` contains a complete example that
-    demonstrates how to work with overloaded operators in more detail.
+    The file :file:`example/example-operator-overloading.cpp` contains a
+    complete example that demonstrates how to work with overloaded operators in
+    more detail.
 
 Callbacks and passing anonymous functions
 =========================================
@@ -209,8 +210,9 @@ The following interactive session shows how to call them from Python.
     This functionality is very useful when generating bindings for callbacks in
     C++ libraries (e.g. GUI libraries, asynchronous networking libraries, etc.).
 
-    The file :file:`example/example5.cpp` contains a complete example that
-    demonstrates how to work with callbacks and anonymous functions in more detail.
+    The file :file:`example/example-callbacks.cpp` contains a complete example
+    that demonstrates how to work with callbacks and anonymous functions in
+    more detail.
 
 Overriding virtual functions in Python
 ======================================
@@ -347,9 +349,9 @@ Please take a look at the :ref:`macro_notes` before using this feature.
 
 .. seealso::
 
-    The file :file:`example/example12.cpp` contains a complete example that
-    demonstrates how to override virtual functions using pybind11 in more
-    detail.
+    The file :file:`example/example-virtual-functions.cpp` contains a complete
+    example that demonstrates how to override virtual functions using pybind11
+    in more detail.
 
 
 .. _macro_notes:
@@ -433,8 +435,8 @@ out of the box with just the core :file:`pybind11/pybind11.h` header.
 
 .. seealso::
 
-    The file :file:`example/example2.cpp` contains a complete example that
-    demonstrates how to pass STL data types in more detail.
+    The file :file:`example/example-python-types.cpp` contains a complete
+    example that demonstrates how to pass STL data types in more detail.
 
 Binding sequence data types, iterators, the slicing protocol, etc.
 ==================================================================
@@ -443,10 +445,10 @@ Please refer to the supplemental example for details.
 
 .. seealso::
 
-    The file :file:`example/example6.cpp` contains a complete example that
-    shows how to bind a sequence data type, including length queries
-    (``__len__``), iterators (``__iter__``), the slicing protocol and other
-    kinds of useful operations.
+    The file :file:`example/example-sequences-and-iterators.cpp` contains a
+    complete example that shows how to bind a sequence data type, including
+    length queries (``__len__``), iterators (``__iter__``), the slicing
+    protocol and other kinds of useful operations.
 
 Return value policies
 =====================
@@ -630,8 +632,8 @@ might be declared as follows:
 
 .. seealso::
 
-    The file :file:`example/example13.cpp` contains a complete example that
-    demonstrates using :class:`keep_alive` in more detail.
+    The file :file:`example/example-keep-alive.cpp` contains a complete example
+    that demonstrates using :class:`keep_alive` in more detail.
 
 Implicit type conversions
 =========================
@@ -832,9 +834,9 @@ Please take a look at the :ref:`macro_notes` before using this feature.
 
 .. seealso::
 
-    The file :file:`example/example8.cpp` contains a complete example that
-    demonstrates how to work with custom reference-counting holder types in
-    more detail.
+    The file :file:`example/example-smart-ptr.cpp` contains a complete example
+    that demonstrates how to work with custom reference-counting holder types
+    in more detail.
 
 .. _custom_constructors:
 
@@ -939,7 +941,7 @@ a first shot at handling the exception).
 Inside the translator, ``std::rethrow_exception`` should be used within
 a try block to re-throw the exception. A catch clause can then use
 ``PyErr_SetString`` to set a Python exception as demonstrated
-in :file:`example19.cpp``.
+in :file:`example-custom-exceptions.cpp``.
 
 This example also demonstrates how to create custom exception types
 with ``py::exception``.
@@ -1077,9 +1079,9 @@ Please take a look at the :ref:`macro_notes` before using this feature.
 
 .. seealso::
 
-    The file :file:`example/example14.cpp` contains a complete example that
-    demonstrates how to create and expose opaque types using pybind11 in more
-    detail.
+    The file :file:`example/example-opaque-types.cpp` contains a complete
+    example that demonstrates how to create and expose opaque types using
+    pybind11 in more detail.
 
 .. _eigen:
 
@@ -1249,8 +1251,8 @@ limitations), refer to the section on :ref:`eigen`.
 
 .. seealso::
 
-    The file :file:`example/example7.cpp` contains a complete example that
-    demonstrates using the buffer protocol with pybind11 in more detail.
+    The file :file:`example/example-buffers.cpp` contains a complete example
+    that demonstrates using the buffer protocol with pybind11 in more detail.
 
 .. [#f2] http://docs.python.org/3/c-api/buffer.html
 
@@ -1398,8 +1400,8 @@ simply using ``vectorize``).
 
 .. seealso::
 
-    The file :file:`example/example10.cpp` contains a complete example that
-    demonstrates using :func:`vectorize` in more detail.
+    The file :file:`example/example-numpy-vectorize.cpp` contains a complete
+    example that demonstrates using :func:`vectorize` in more detail.
 
 Functions taking Python objects as arguments
 ============================================
@@ -1462,9 +1464,10 @@ with other parameters.
 
 .. seealso::
 
-    The file :file:`example/example2.cpp` contains a complete example that
-    demonstrates passing native Python types in more detail. The file
-    :file:`example/example11.cpp` discusses usage of ``args`` and ``kwargs``.
+    The file :file:`example/example-python-types.cpp` contains a complete
+    example that demonstrates passing native Python types in more detail. The
+    file :file:`example/example-arg-keywords-and-defaults.cpp` discusses usage
+    of ``args`` and ``kwargs``.
 
 Default arguments revisited
 ===========================
@@ -1537,11 +1540,11 @@ Such functions can also be created using pybind11:
    /// Binding code
    m.def("generic", &generic);
 
-(See ``example/example11.cpp``). The class ``py::args`` derives from
-``py::list`` and ``py::kwargs`` derives from ``py::dict`` Note that the
-``kwargs`` argument is invalid if no keyword arguments were actually provided.
-Please refer to the other examples for details on how to iterate over these,
-and on how to cast their entries into C++ objects.
+(See ``example/example-arg-keywords-and-defaults.cpp``). The class ``py::args``
+derives from ``py::list`` and ``py::kwargs`` derives from ``py::dict`` Note
+that the ``kwargs`` argument is invalid if no keyword arguments were actually
+provided.  Please refer to the other examples for details on how to iterate
+over these, and on how to cast their entries into C++ objects.
 
 Partitioning code over multiple extension modules
 =================================================
@@ -1682,8 +1685,9 @@ memory corruption and/or segmentation faults.
 
 .. seealso::
 
-    The file :file:`example/example15.cpp` contains a complete example that
-    demonstrates how to pickle and unpickle types using pybind11 in more detail.
+    The file :file:`example/example-pickling.cpp` contains a complete example
+    that demonstrates how to pickle and unpickle types using pybind11 in more
+    detail.
 
 .. [#f3] http://docs.python.org/3/library/pickle.html#pickling-class-instances
 

example/CMakeLists.txt

@@ -7,25 +7,25 @@ if(NOT CMAKE_BUILD_TYPE AND NOT CMAKE_CONFIGURATION_TYPES)
 endif()
 
 set(PYBIND11_EXAMPLES
-  example1.cpp
-  example2.cpp
-  example3.cpp
-  example4.cpp
-  example5.cpp
-  example6.cpp
-  example7.cpp
-  example8.cpp
-  example9.cpp
-  example10.cpp
-  example11.cpp
-  example12.cpp
-  example13.cpp
-  example14.cpp
-  example15.cpp
-  example16.cpp
-  example17.cpp
-  example18.cpp
-  example19.cpp
+  example-methods-and-attributes.cpp
+  example-python-types.cpp
+  example-operator-overloading.cpp
+  example-constants-and-functions.cpp
+  example-callbacks.cpp
+  example-sequences-and-iterators.cpp
+  example-buffers.cpp
+  example-smart-ptr.cpp
+  example-modules.cpp
+  example-numpy-vectorize.cpp
+  example-arg-keywords-and-defaults.cpp
+  example-virtual-functions.cpp
+  example-keep-alive.cpp
+  example-opaque-types.cpp
+  example-pickling.cpp
+  example-inheritance.cpp
+  example-stl-binder-vector.cpp
+  example-eval.cpp
+  example-custom-exceptions.cpp
   issues.cpp
 )
 

example/example11.cpp → example/example-arg-keywords-and-defaults.cpp

 /*
-    example/example11.cpp -- keyword arguments and default values
+    example/example-arg-keywords-and-defaults.cpp -- keyword arguments and default values
 
     Copyright (c) 2016 Wenzel Jakob <wenzel.jakob@epfl.ch>
 
@@ -40,7 +40,7 @@ void args_kwargs_function(py::args args, py::kwargs kwargs) {
     }
 }
 
-void init_ex11(py::module &m) {
+void init_ex_arg_keywords_and_defaults(py::module &m) {
     m.def("kw_func", &kw_func, py::arg("x"), py::arg("y"));
     m.def("kw_func2", &kw_func, py::arg("x") = 100, py::arg("y") = 200);
     m.def("kw_func3", [](const char *) { }, py::arg("data") = std::string("Hello world!"));

example/example7.cpp → example/example-buffers.cpp

 /*
-    example/example7.cpp -- supporting Pythons' buffer protocol
+    example/example-buffers.cpp -- supporting Pythons' buffer protocol
 
     Copyright (c) 2016 Wenzel Jakob <wenzel.jakob@epfl.ch>
 
@@ -73,7 +73,7 @@ private:
     float *m_data;
 };
 
-void init_ex7(py::module &m) {
+void init_ex_buffers(py::module &m) {
     py::class_<Matrix> mtx(m, "Matrix");
 
     mtx.def(py::init<size_t, size_t>())

example/example5.cpp → example/example-callbacks.cpp

 /*
-    example/example5.cpp -- inheritance, callbacks, acquiring and releasing the
-    global interpreter lock
+    example/example-callbacks.cpp -- callbacks
 
     Copyright (c) 2016 Wenzel Jakob <wenzel.jakob@epfl.ch>
 
@@ -12,36 +11,6 @@
 #include <pybind11/functional.h>
 
 
-class Pet {
-public:
-    Pet(const std::string &name, const std::string &species)
-        : m_name(name), m_species(species) {}
-    std::string name() const { return m_name; }
-    std::string species() const { return m_species; }
-private:
-    std::string m_name;
-    std::string m_species;
-};
-
-class Dog : public Pet {
-public:
-    Dog(const std::string &name) : Pet(name, "dog") {}
-    void bark() const { std::cout << "Woof!" << std::endl; }
-};
-
-class Rabbit : public Pet {
-public:
-    Rabbit(const std::string &name) : Pet(name, "parrot") {}
-};
-
-void pet_print(const Pet &pet) {
-    std::cout << pet.name() + " is a " + pet.species() << std::endl;
-}
-
-void dog_bark(const Dog &dog) {
-    dog.bark();
-}
-
 bool test_callback1(py::object func) {
     func();
     return false;
@@ -88,24 +57,7 @@ void test_dummy_function(const std::function<int(int)> &f) {
     }
 }
 
-void init_ex5(py::module &m) {
-    py::class_<Pet> pet_class(m, "Pet");
-    pet_class
-        .def(py::init<std::string, std::string>())
-        .def("name", &Pet::name)
-        .def("species", &Pet::species);
-
-    /* One way of declaring a subclass relationship: reference parent's class_ object */
-    py::class_<Dog>(m, "Dog", pet_class)
-        .def(py::init<std::string>());
-
-    /* Another way of declaring a subclass relationship: reference parent's C++ type */
-    py::class_<Rabbit>(m, "Rabbit", py::base<Pet>())
-        .def(py::init<std::string>());
-
-    m.def("pet_print", pet_print);
-    m.def("dog_bark", dog_bark);
-
+void init_ex_callbacks(py::module &m) {
     m.def("test_callback1", &test_callback1);
     m.def("test_callback2", &test_callback2);
     m.def("test_callback3", &test_callback3);

example/example4.cpp → example/example-constants-and-functions.cpp

 /*
-    example/example4.cpp -- global constants and functions, enumerations, raw byte strings
+    example/example-constants-and-functions.cpp -- global constants and functions, enumerations, raw byte strings
 
     Copyright (c) 2016 Wenzel Jakob <wenzel.jakob@epfl.ch>
 
@@ -14,7 +14,7 @@ enum EMyEnumeration {
     ESecondEntry
 };
 
-class Example4 {
+class ExampleWithEnum {
 public:
     enum EMode {
         EFirstMode = 1,
@@ -22,7 +22,7 @@ public:
     };
 
     static EMode test_function(EMode mode) {
-        std::cout << "Example4::test_function(enum=" << mode << ")" << std::endl;
+        std::cout << "ExampleWithEnum::test_function(enum=" << mode << ")" << std::endl;
         return mode;
     }
 };
@@ -52,7 +52,7 @@ void print_bytes(py::bytes bytes) {
         std::cout << "bytes[" << i << "]=" << (int) value[i] << std::endl;
 }
 
-void init_ex4(py::module &m) {
+void init_ex_constants_and_functions(py::module &m) {
     m.def("test_function", &test_function1);
     m.def("test_function", &test_function2);
     m.def("test_function", &test_function3);
@@ -63,11 +63,11 @@ void init_ex4(py::module &m) {
         .value("ESecondEntry", ESecondEntry)
         .export_values();
 
-    py::class_<Example4> ex4_class(m, "Example4");
-    ex4_class.def_static("test_function", &Example4::test_function);
-    py::enum_<Example4::EMode>(ex4_class, "EMode")
-        .value("EFirstMode", Example4::EFirstMode)
-        .value("ESecondMode", Example4::ESecondMode)
+    py::class_<ExampleWithEnum> exenum_class(m, "ExampleWithEnum");
+    exenum_class.def_static("test_function", &ExampleWithEnum::test_function);
+    py::enum_<ExampleWithEnum::EMode>(exenum_class, "EMode")
+        .value("EFirstMode", ExampleWithEnum::EFirstMode)
+        .value("ESecondMode", ExampleWithEnum::ESecondMode)
         .export_values();
 
     m.def("return_bytes", &return_bytes);

example/example4.py → example/example-constants-and-functions.py

@@ -7,7 +7,7 @@ from example import test_function
 from example import some_constant
 from example import EMyEnumeration
 from example import EFirstEntry
-from example import Example4
+from example import ExampleWithEnum
 from example import return_bytes
 from example import print_bytes
 
@@ -25,34 +25,34 @@ print("integer->enum = %s" % str(EMyEnumeration(2)))
 
 print("A constant = " + str(some_constant))
 
-print(Example4.EMode)
-print(Example4.EMode.EFirstMode)
-print(Example4.EFirstMode)
-Example4.test_function(Example4.EFirstMode)
+print(ExampleWithEnum.EMode)
+print(ExampleWithEnum.EMode.EFirstMode)
+print(ExampleWithEnum.EFirstMode)
+ExampleWithEnum.test_function(ExampleWithEnum.EFirstMode)
 
 print("Equality test 1: " + str(
-    Example4.test_function(Example4.EFirstMode) ==
-    Example4.test_function(Example4.EFirstMode)))
+    ExampleWithEnum.test_function(ExampleWithEnum.EFirstMode) ==
+    ExampleWithEnum.test_function(ExampleWithEnum.EFirstMode)))
 
 print("Inequality test 1: " + str(
-    Example4.test_function(Example4.EFirstMode) !=
-    Example4.test_function(Example4.EFirstMode)))
+    ExampleWithEnum.test_function(ExampleWithEnum.EFirstMode) !=
+    ExampleWithEnum.test_function(ExampleWithEnum.EFirstMode)))
 
 print("Equality test 2: " + str(
-    Example4.test_function(Example4.EFirstMode) ==
-    Example4.test_function(Example4.ESecondMode)))
+    ExampleWithEnum.test_function(ExampleWithEnum.EFirstMode) ==
+    ExampleWithEnum.test_function(ExampleWithEnum.ESecondMode)))
 
 print("Inequality test 2: " + str(
-    Example4.test_function(Example4.EFirstMode) !=
-    Example4.test_function(Example4.ESecondMode)))
+    ExampleWithEnum.test_function(ExampleWithEnum.EFirstMode) !=
+    ExampleWithEnum.test_function(ExampleWithEnum.ESecondMode)))
 
 x = {
-        Example4.test_function(Example4.EFirstMode): 1,
-        Example4.test_function(Example4.ESecondMode): 2
+        ExampleWithEnum.test_function(ExampleWithEnum.EFirstMode): 1,
+        ExampleWithEnum.test_function(ExampleWithEnum.ESecondMode): 2
 }
 
-x[Example4.test_function(Example4.EFirstMode)] = 3
-x[Example4.test_function(Example4.ESecondMode)] = 4
+x[ExampleWithEnum.test_function(ExampleWithEnum.EFirstMode)] = 3
+x[ExampleWithEnum.test_function(ExampleWithEnum.ESecondMode)] = 4
 print("Hashing test = " + str(x))
 
 print_bytes(return_bytes())

example/example4.ref → example/example-constants-and-functions.ref

@@ -16,23 +16,23 @@ A constant = 14
 <class 'example.EMode'>
 EMode.EFirstMode
 EMode.EFirstMode
-Example4::test_function(enum=1)
-Example4::test_function(enum=1)
-Example4::test_function(enum=1)
+ExampleWithEnum::test_function(enum=1)
+ExampleWithEnum::test_function(enum=1)
+ExampleWithEnum::test_function(enum=1)
 Equality test 1: True
-Example4::test_function(enum=1)
-Example4::test_function(enum=1)
+ExampleWithEnum::test_function(enum=1)
+ExampleWithEnum::test_function(enum=1)
 Inequality test 1: False
-Example4::test_function(enum=1)
-Example4::test_function(enum=2)
+ExampleWithEnum::test_function(enum=1)
+ExampleWithEnum::test_function(enum=2)
 Equality test 2: False
-Example4::test_function(enum=1)
-Example4::test_function(enum=2)
+ExampleWithEnum::test_function(enum=1)
+ExampleWithEnum::test_function(enum=2)
 Inequality test 2: True
-Example4::test_function(enum=1)
-Example4::test_function(enum=2)
-Example4::test_function(enum=1)
-Example4::test_function(enum=2)
+ExampleWithEnum::test_function(enum=1)
+ExampleWithEnum::test_function(enum=2)
+ExampleWithEnum::test_function(enum=1)
+ExampleWithEnum::test_function(enum=2)
 Hashing test = {EMode.EFirstMode: 3, EMode.ESecondMode: 4}
 bytes[0]=1
 bytes[1]=0

example/example19.cpp → example/example-custom-exceptions.cpp

 /*
-    example/example19.cpp -- exception translation
+    example/example-custom-exceptions.cpp -- exception translation
 
     Copyright (c) 2016 Pim Schellart <P.Schellart@princeton.edu>
 
@@ -66,7 +66,7 @@ void throws_logic_error() {
     throw std::logic_error("this error should fall through to the standard handler");
 }
 
-void init_ex19(py::module &m) {
+void init_ex_custom_exceptions(py::module &m) {
     // make a new custom exception and use it as a translation target
     static py::exception<MyException> ex(m, "MyException");
     py::register_exception_translator([](std::exception_ptr p) {

example/example18.cpp → example/example-eval.cpp

 /*
-    example/example18.cpp -- Usage of eval() and eval_file()
+    example/example-eval.cpp -- Usage of eval() and eval_file()
 
     Copyright (c) 2016 Klemens D. Morgenstern
 
@@ -11,7 +11,7 @@
 #include <pybind11/eval.h>
 #include "example.h"
 
-void example18() {
+void example_eval() {
     py::module main_module = py::module::import("__main__");
     py::object main_namespace = main_module.attr("__dict__");
 
@@ -59,9 +59,9 @@ void example18() {
     main_module.def("call_test2", [&](int value) {val_out = value;});
 
     try {
-        result = py::eval_file("example18_call.py", main_namespace);
+        result = py::eval_file("example-eval_call.py", main_namespace);
     } catch (...) {
-        result = py::eval_file("example/example18_call.py", main_namespace);
+        result = py::eval_file("example/example-eval_call.py", main_namespace);
     }
 
     if (val_out == 42 && result == py::none())
@@ -97,6 +97,6 @@ void example18() {
         cout << "eval_file failure test failed" << endl;
 }
 
-void init_ex18(py::module & m) {
-    m.def("example18", &example18);
+void init_ex_eval(py::module & m) {
+    m.def("example_eval", &example_eval);
 }

example/example-eval.py

+from example import example_eval
+
+example_eval()
+
+