First version of my book proposal for Wrox

1 files changed, 340 insertions, 0 deletions

diff --git a/oop/intro.rst b/oop/intro.rst
new file mode 100644
index 0000000..1e3513e
--- /dev/null
+++ b/oop/intro.rst
@@ -0,0 +1,340 @@
+.. -*- mode: rst -*-
+
+Book Proposal: Object Oriented Python
+============================================
+
+:Author: Michele Simionato
+:Version: 0.1
+:Date: 2009-03-13
+:Status: Draft
+
+This book focuses on the Object Oriented aspects of Python. 
+However, it does not try to emphasize general topics of OOP that are
+exportable to other languages. Instead, its aim is to
+emphasize specific techniques which are exquisitely Pythonic.
+One of the goals of this book is to enable you *to program Python in Python*
+and not in Java, in C++, or in your favorite language.
+To this aim, the Python object model is discussed in detail, since
+it is quite different from the object model of most languages and it
+provides many features which is important to know, even if you choose
+to not use it. The goal of this book is to  
+
+
+The text before the first heading should introduce the reader to the
+aims and scope of this book in the context of current trends in the
+field, current technology, and so on. What issues are important? What
+compelled you to write this book?
+
+ .. line-block::
+
+  *There is only one way to learn: trough examples*
+
+The Philosophy Of This Book
+---------------------------
+
+This book is written with the intent to help the programmer going trough
+the fascinating concepts of Object Oriented Programming (OOP), in their
+Python incarnation. Notice that I say to help, not to teach. Actually,
+I do not think that a book can teach OOP or any other non-trivial matter 
+in Computer Science or other disciplines. Only the
+practice can teach: practice, then practice, and practice again. 
+You must learn yourself from your experiments, not from the books. 
+Nevertheless, books are useful. They cannot teach, but they can help. 
+They should give you new ideas that you was not thinking about, they should
+show tricks you do not find in the manual, and in general they should be of
+some guidance in the uphill road to knowledge. That is the philosophy
+of this book. For this reason
+
+1. It is not comprehensive, not systematic; 
+it is intended to give ideas and basis: from
+that the reader is expected to cover the missing part on his own,
+browsing the documentation, other sources and other books, and finally
+the definite autority, the source itself.
+
+2. It will not even try to teach the *best* practices. I will show what you can
+do with Python, not what you "should" do. Often I will show solutions that are
+not recommended. I am not a mammy saying this is
+good, this is bad, do this do that.  
+
+
+3. You can only learn from your failures. If you think "it should work, if I do
+X and Y" and it works, then you have learned nothing new. 
+You have merely verified
+that your previous knowledge was correct, but you haven't create a new
+knowledge. On the other hand, when you think "it should work, if I do
+X and Y" and it doesn't, then you have learned that your previous knowlegde
+was wrong or incomplete, and you are forced to learn something new to
+overcome the difficulty. For this reason, I think it is useful to report
+not only how to do something, but also to report how not to do something, 
+showing the pitfalls of wrong approaches.
+
+That's in my opinion is the goal of a good book. I don't know if have
+reached this goal or not (the decision is up to the reader), but at least
+I have tried to follow these guidelines.
+
+Moreover, this is not a book on OOP, 
+it is a book on OOP *in Python*. 
+
+In other words, the point of view of this book is not 
+to emphasize general topics of OOP that are exportable to other languages, 
+but exactly the opposite: I want to emphasize specific techniques that one
+can only use in Python, or that are difficult to translate to other 
+languages. Moreover, I will not provide comparisons with other 
+languages (except for the section "Why Python?" in this introduction and
+in few selected other places), 
+in order to keep the discussion focused. 
+
+This choice comes from the initial motivation for this book, which was 
+to fulfill a gap in the (otherwise excellent) Python documentation. 
+The problem is that the available documentation still lacks an accessible 
+reference of the new Python 2.2+ object-oriented features.
+Since myself I have learned Python and OOP from scratch, 
+I have decided to write this book in order to fill that gap and
+help others. 
+
+The emphasis in this book is not in giving 
+solutions to specific problems (even if most of the recipes of this book
+can easily be tailored to solve real life concrete problems), it is in 
+teaching  how does it work, why it does work in some cases and why does 
+not work in some other cases. Avoiding too specific problems has an
+additional bonus, since it allows me to use *short* examples (the majority 
+of the scripts presented here is under 20-30 lines) which I think are 
+best suited to teach a new matter [#]_ . Notice, however, that whereas
+the majority of the scripts in this book are short, it is also true
+that they are pretty *dense*. The density is due to various reasons:
+
+1. I am defining a lot of helper functions and classes, that are
+   reused and enhanced during all the book.
+
+2. I am doing a strong use of inheritance, therefore a script at the
+   end of the book can inherits from the classes defined through all
+   the book;
+
+3. A ten line script involving metaclasses can easily perform the equivalent 
+   of generating hundreds of lines of code in a language without metaclasses 
+   such as Java or C++.
+
+To my knowledge, there are no other books covering the same topics with
+the same focus (be warned, however, that I haven't read so many Python 
+books ;-). The two references that come closest to the present book are
+the ``Python Cookbook`` by Alex Martelli and David Ascher, and
+Alex Martelli's ``Python in a Nutshell``. They are quite recent books and 
+therefore it covers (in much less detail) some of the 2.2 features that are 
+the central topics to this book. 
+However, the Cookbook reserves to OOP only one chapter and has a quite 
+different philosophy from the present book, therefore there is 
+practically no overlapping. Also ``Python in a Nutshell`` covers 
+metaclasses in few pages, whereas half of this book is essentially
+dedied to them. This means that you can read both ;-)
+ 
+
+.. [#] Readers that prefer the  opposite philosophy of using longer, 
+       real life-like, examples, have already the excellent "Dive into 
+       Python" book http://diveintopython.org/ at their disposal. This is 
+       a very good book that I certainly recommend to any (experienced) 
+       Python programmer; it is also freely available (just like this ;-).
+       However, the choice of arguments is quite different and there is 
+       essentially no overlap between my book and "Dive into Python" 
+       (therefore you can read both ;-).
+
+Who This Book Is For
+------------------------------------------------
+
+I have tried to make this book useful to a large public of Pythonistas, 
+i.e. both people with no previous experience of Object Oriented Programming
+and people with experience on OOP, but unfamiliar with the most
+recent Python 2.2-2.3 features (such as attribute descriptors,
+metaclasses, change of the MRO in multiple inheritance, etc). 
+However, this is not a book for beginners: the non-experienced reader should 
+check (at least) the Internet sites http://www.python.org/newbies.com and 
+http://www.awaretek.com, that provide a nice collection of resources for Python 
+newbies.
+
+These are my recommendations for the reader, according to her/his level:
+
+1. If you are an absolute beginner, with no experience on programming,
+   this book is *not* for you (yet ;-). Go to 
+   http://www.python.org/doc/Newbies.html and read one of the introductive 
+   texts listed there, then come back here. I recommend "How to Think Like 
+   a Computer Scientist", available for free on the net (see 
+   http://www.ibiblio.org/obp/thinkCSpy/); I found it useful myself when 
+   I started learning Python; be warned, however, that it refers to a rather 
+   old Python version. There are also excellent books 
+   on the market (see http://www.awaretek.com/plf.html). 
+   http://www.uselesspython.com/ is a good resource to find recensions 
+   about available Python books. For free books, look at
+   http://www.tcfb.com/freetechbooks/bookphyton.html .
+
+2. If you know already (at least) another programming language, but you don't
+   know Python, then this book is *not* for you (again ;-). Read the FAQ, the
+   Python Tutorial and play a little with the Standard Library (all this
+   material can be downloaded for free from  http://www.python.org), then
+   come back here. 
+
+3. If you have passed steps 1 and 2, and you are confortable with Python
+   at the level of simple procedural programming, but have no clue about
+   objects and classes, *then* this book is for you. Read this book till
+   the end and your knowledge of OOP will pass from zero to a quite advanced 
+   level (hopefully). Of course, you will have to play with the code in 
+   this book and write a lot of code on your own, first ;-)    
+
+4. If you are confortable with Python and you also known OOP from other
+   languages or from earlier version of Python, then this book is for
+   you, too: you are ready to read the more advanced chapters.
+
+5. If you are a Python guru, then you should read the book, too. I expect
+   you will find the errors and send me feedback, helping me to improve
+   this book.
+
+
+What This Book Covers
+--------------------------------------------------
+
+This book covers Python 3.1, which is the most recent release of Python
+(actually not yet released as I write now). All the examples and the code
+in this book runs under Python 3.1, with a few exceptions when talking about
+backward compatibility; the code which is meant to be run under older
+version of Python is explicitely marked as so. Since at the present most
+Python code in existence runs on Python 2.X, the book contains an appendix
+about older version of Python and how to run the examples if you are stuck
+with an older Python.
+
+How This Book Is Structured
+---------------------------------------------------------------------
+
+This book is split in two parts. Parts I, titled "The Python Object Model"
+is an in deep review of the Python object model, from the basics to
+advanced topics such as descriptors, multiple inheritance and metaclasses, 
+The main focus of part I is to make the reader confortable with what
+Python has to offer in this respect (*know your toolbox*). In particular
+the differences with more static object models (say the Java or the C++
+object model) and highlighted and the advantages of the dynamic features
+of Python are emphasized.
+
+Part II is titled "Putting the Python Object model to work" is a sequence
+of case studies, with the intend of showing real life non-trivial 
+applications of Python features (*use your toolbox*). 
+There is a difference between merely *knowing* a technique and 
+*being able to use* it effectively. Knowing just requires study;
+using effectively requires a maturity which is only won with hard
+work, lots of practice, and lots of mistakes: in a word, we call all
+of that *experience*. 
+
+Therefore, whereas Part I is more pedagogical in intent, Part II focuses
+on design decisions and discussion of best practices: given two
+or more possible solutions for a problem, which one is the best
+solution in terms of simplicity, extensibility, maintenability, and so
+on? When it is sensible to use a technique and when it is better *not*
+to use it? All the discussion is based on real life case studies 
+coming from my working experience.
+
+If you are already an experienced Python coder you will find Part II
+to be the most interesting one; on the other hand, if you are just
+beginning with Python you should probably focus more on Part I and
+read part II in a second moment, when you have become acquainted with
+the language. On the other hand, everybody is free to read the book as
+he/she whishes, and you find more rewarding to skip chapters and to
+read sections here and however. However, I have written this book
+for cover-to-cover readers, since. I am one of them myself. Actually,
+the only books I do read cover-to-cover are reference
+books and books which are collections of papers.
+
+What You Need to Use This Book
+--------------------------------------------------
+
+You do not need much to use this book. Just a computer, an editor, the
+latest release of Python and an open mind. All the code described in
+this book is cross platform, so you should not have any trouble whatever
+your platform is. Sometimes for convenience I just how to run an example
+from the Linux command line since Linux is the platform I am using 
+to write the book, but you can freely replace the Linux command line
+with the Windows or the Mac ones, with the obvious substitutions.
+
+How this book is written
+----------------------------------------------------------------------
+
+I am writing this book on a MacBook running Ubuntu Linux, using Emacs as
+editor, reStructuredText as text format and subversion as version control
+system. The content of the book is scattered in many Python files with big
+docstrings. I am using a toolchain
+based on docutils and Sphynx to generate the book from the Python files.
+The advantage of this approach is that the entire codebase of the book
+is continuously tested, and I can be confident than I am distributing correct
+code. As testing frameworks I am using doctest from the standard library
+and nosetest, which is not standard, but well known in the community.
+
+.. All the code of this book is available as a public subversion repository 
+.. (if the editor allows me).
+
+Source Code
+-----------------------------------------------------------------
+
+All of the source code used in this book is
+available for download at http://www.wrox.com. Once at the site,
+simply locate the book’s title (either by using the Search box or by
+using one of the title lists) and click the Download Code link on the
+book’s detail page to obtain all the source code for the book.
+
+Because many books have similar
+titles, you may find it easiest to search by ISBN; this book’s ISBN
+is 978-0-47X-XXXXX-X.  Once you download the code, just decompress it
+with your favorite compression tool. Alternately, you can go to the
+main Wrox code download page at
+http://www.wrox.com/dynamic/books/download.aspx to see the code
+available for this book and all other Wrox books.  Errata We make
+every effort to ensure that there are no errors in the text or in the
+code. However, no one is perfect, and mistakes do occur. If you find
+an error in one of our books, like a spelling mistake or faulty piece
+of code, we would be very grateful for your feedback. By sending in
+errata you may save another reader hours of frustration and at the
+same time you will be helping us provide even higher quality
+information.  To find the errata page for this book, go to
+http://www.wrox.com and locate the title using the Search box or one
+of the title lists. Then, on the book details page, click the Book
+Errata link. On this page you can view all errata that has been
+submitted for this book and posted by Wrox editors. A complete book
+list including links to each book’s errata is also available at
+http://www.wrox.com/misc-pages/booklist.shtml.  If you don’t spot “your”
+error on the Book Errata page, go to
+http://www.wrox.com/contact/techsupport.shtml and complete the form there to
+send us the error you have found. We’ll check the information and, if
+appropriate, post a message to the book’s errata page and fix the
+problem in subsequent editions of the book.  p2p.wrox.com For author
+and peer discussion, join the P2P forums at p2p.wrox.com. The forums
+are a Web-based system for you to post messages relating to Wrox books
+and related technologies and interact with other readers and
+technology users. The forums offer a subscription feature to e-mail
+you topics of interest of your choosing when new posts are made to the
+forums. Wrox authors, editors, other industry experts, and your fellow
+readers are present on these forums.  At http://p2p.wrox.com you will
+find a number of different forums that will help you not only as you
+read this book, but also as you develop your own applications. To join
+the forums, just follow these steps: 
+
+1. Go to p2p.wrox.com and click the Register link.  
+
+2. Read the terms of use and click Agree.
+
+3. Complete the required information to join as well as any optional
+   information you wish to provide and click Submit.  
+
+4. You will receive an e-mail with information describing how to
+   verify your account and complete the joining process.  You can read
+   messages in the forums without joining P2P but in order to post your
+   own messages, you must join.  Once you join, you can post new messages
+   and respond to messages other users post. You can read messages at any
+   time on the Web. If you would like to have new messages from a
+   particular forum e-mailed to you, click the Subscribe to this Forum
+   icon by the forum name in the forum listing.  For more information
+   about how to use the Wrox P2P, be sure to read the P2P FAQs for
+   answers to questions about how the forum software works as well as
+   many common questions specific to P2P and Wrox books. To read the
+   FAQs, click the FAQ link on any P2P page.
+
+.. Sometimes Python is accused of having too many web frameworks. And
+.. it's true, there are a lot. That said, I think writing a framework
+.. is a useful exercise. It doesn't let you skip over too much
+.. without understanding it. It removes the magic. So even if you go
+.. on to use another existing framework (which I'd probably advise
+.. you do), you'll be able to understand it better if you've written
+.. something like it on your own. - Ian Bicking, http://pythonpaste.org/webob/do-it-yourself.html