doc/alphaapi.html


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

<html>
<head>
    <link href="style.css" rel="stylesheet" type="text/css"></link>
    <link href="docs.css" rel="stylesheet" type="text/css"></link>
    <script src="scripts.js"></script>
    <title>SQLAlchemy Documentation</title>
</head>
<body>
    <h3>What is an Alpha API Feature?</h3>
<p><b>Alpha API</b> indicates that the best way for a particular feature to be presented hasn't been firmly settled on as of yet, and the current way is being introduced on a trial basis.  Its spirit is not as much a warning that "this API might change", its more an invitation to the users saying, "heres a new idea I had.  I'm not sure if this is the best way to do it.  Do you like it ?  Should we do this differently?  Or is it good the way it is ?".  Alpha API features are always small in scope and are presented in releases so that the greatest number of users get some hands-on experience with it;  large-scoped API or architectural changes will always be discussed on the mailing list/Wiki first.</p>

<p>Reasons why a feature might want to change include:
    <ul>
        <li>The API for the feature is too difficult to use for the typical task, and needs to be more "convenient"</li>
        <li>The feature only implements a subsection of what it really should be doing</li>
        <li>The feature's interface is inconsistent with that of other features which operate at a similar level</li>
        <li>The feature is confusing and is often misunderstood, and would be better replaced by a more manual feature that makes the task clearer</li>
        <li>The feature overlaps with another feature and effectively provides too many ways to do the same thing</li>
        <li>The feature made some assumptions about the total field of use cases which is not really true, and it breaks in other scenarios</li>
    </ul>
    
</p>
<p>A good example of what was essentially an "alpha feature" is the <code>private=True</code> flag.  This flag on a <code>relation()</code> indicates that child objects should be deleted along with the parent.  After this flag experienced some usage by the SA userbase, some users remarked that a more generic and configurable way was Hibernates <code>cascade="all, delete-orphan"</code>, and also that the term <code>cascade</code> was clearer in purpose than the more ambiguous <code>private</code> keyword, which could be construed as a "private variable".</p>

<center><input type="button" value="close window" onclick="window.close()"></center>
</body>
</html>