diff options
author | Travis Oliphant <oliphant@enthought.com> | 2005-10-12 05:21:47 +0000 |
---|---|---|
committer | Travis Oliphant <oliphant@enthought.com> | 2005-10-12 05:21:47 +0000 |
commit | dce41a2a15d9be0cd2cd592ed209b7f30ce166ee (patch) | |
tree | ba747c1ce3d894a6c9f7f35f22fc01c8328842c1 /doc | |
parent | 8c1d5fa4cff205667a48ffbb8936bac5e7e59beb (diff) | |
download | numpy-dce41a2a15d9be0cd2cd592ed209b7f30ce166ee.tar.gz |
Moved doc to subdir of scipy
Diffstat (limited to 'doc')
-rw-r--r-- | doc/CAPI.txt | 314 | ||||
-rw-r--r-- | doc/DISTUTILS.txt | 338 | ||||
-rw-r--r-- | doc/README.txt | 15 |
3 files changed, 0 insertions, 667 deletions
diff --git a/doc/CAPI.txt b/doc/CAPI.txt deleted file mode 100644 index cdda9394e..000000000 --- a/doc/CAPI.txt +++ /dev/null @@ -1,314 +0,0 @@ -Author: Travis Oliphant -Discussions to: scipy-dev@scipy.org -Created: October 2005 - -The CAPI of SciPy is (mostly) backward compatible with Numeric. - -There are a few non-standard Numeric usages (that were not really part -of the API) that will need to be changed: - - * If you used any of the function pointers in the PyArray_Descr - structure you will have to modify your usage of those. The - casting functions have eliminated the strides argument (use - PyArray_CastTo if you need strided casting). All functions have - one or two PyArrayObject * arguments at the end. This allows the - flexible arrays and mis-behaved arrays to be handled. - - * The descr->zero and descr->one constants have been replaced with - function calls, PyArray_Zero, and PyArray_One. - - * You should use PyArray_ITEMSIZE(obj) instead of descr->elsize to - get the itemsize of an object (for flexible arrays descr->elsize - is 0). - - * If you passed array->dimensions and array->strides around to - functions. These are now, intp* pointers. On 32-bit systems - there won't be a problem. However, on 64-bit systems, you will - need to make changes. - - -The header files arrayobject.h and ufuncobject.h contain many defines -that you may find useful. The files __ufunc_api.h and -__multiarray_api.h contain the available C-API function calls with -their function signatures. - -All of these headers are installed to - -<YOUR_PYTHON_LOCATION>/site-packages/scipy/base/include - - -Getting arrays in C-code -========================= - -All new arrays can be created using PyArray_New. A simple interface -equivalent to PyArray_FromDims is PyArray_SimpleNew(nd, dims, typenum) - -This is a very flexible function. - -PyObject * PyArray_New(PyTypeObject *subtype, int nd, intp *dims, int type, - intp *strides, char *data, int itemsize, int flags, - PyObject *obj); - - -subtype : The subtype that should be created (either pass in - &PyArray_Type, &PyBigArray_Type, or obj->ob_type, - where obj is a subtype (or subclass) of - of PyArray_Type or PyBigArray_Type). - -nd : The number of dimensions (<MAX_DIMS) - -*dims : A pointer to the size in each dimension. Information will be - copied from here. - -type : An integer specifying the type of the array - (use the PyArray_XXXX enumerated types). - -*strides : The strides this array should have. For new arrays created - by this routine, this should be NULL. If you pass in - memory for this array to use, then you should pass in the - strides information as well. Any strides will be copied into - the array structure. Do not pass in bad strides information. - - PyArray_CheckStrides(...) can help but you must call it if you are - unsure. - -*data : NULL for creating brand-new memory. If you want this array - to wrap another memory area, then pass the pointer here. - You are responsible for deleting the memory in that case, - but do not do so until the new array object has been - deleted. The best way to handle that is to get the memory - from another Python object, INCREF that Python object after - passing it's data pointer to this routine, and set the - ->base member of the returned array to the Python object. - You are responsible for setting the base object. Failure - to do so will create a memory leak. - - If you pass in a data buffer, the flags argument will be - the flags of the new array. If you create a new array, a - non-zero flags argument indicates that you want the array - to be in FORTRAN order. - -itemsize : Indicates the itemsize for the new array. This can be 0 - if it is a fixed-size array type. It is only used for - flexible array types and must be set in that case. - - -flags : Either the flags showing how to interpret the data buffer - passed in. Or if a new array is created, nonzero to - indicate a FORTRAN order array. See below for an explanation of - the flags. - - -obj : If subtypes is &PyArray_Type or &PyBigArray_Type, this - argument is ignored. Otherwise, the __array_finalize__ - method of the subtype is called (if present) and passed - this object. This is usually an array of the type to be - created (so the __array_finalize__ method must handle an - array argument. But, it can be anything...) - -Note: The returned array object will be unitialized unless the type is -PyArray_OBJECT. - -PyArray_SimpleNew(nd, dims, typenum) is a drop-in replacement for -PyArray_FromDims (except it takes intp* dims instead of int* dims which - matters on 64-bit systems). - -PyArray_SimpleNew is just a macro for PyArray_New with default arguments. - - -The PyArray_FromDims and family of functions are still available and -are loose wrappers around this function. These functions still take -int * arguments. This should be fine on 32-bit systems, but on 64-bit -systems you may run into trouble if you frequently passed -PyArray_FromDims the dimensions member of the old PyArrayObject structure -because sizeof(intp) != sizeof(int). - - -Getting an arrayobject from an arbitrary Python object -============================================================== - -PyArray_FromAny(...) - -This function replaces PyArray_ContiguousFromObject and friends (those -function calls still remain but they are loose wrappers around the -PyArray_FromAny call). - -static PyObject * -PyArray_FromAny(PyObject *op, PyArray_Typecode *typecode, int min_depth, - int max_depth, int requires) - - -op : The Python object to "convert" to an array object - -typecode : A typecode structure filled with the data type and - itemsize of the desired data type. This can be NULL, if - the type should be determined from the object. Unless - FORCECAST is present in flags, this call will generate - an error if the data type cannot be safely obtained from - the object. - -min_depth : The minimum depth of array needed or 0 if doesn't matter - -max_depth : The maximum depth of array allowed or 0 if doesn't matter - -requires : A flag indicating the "requirements" of the returned array. - - -From the code comments, the requires flag is explained. - -requires can be any of - - CONTIGUOUS, - FORTRAN, (or set typecode->fortran=1) - ALIGNED, - NOTSWAPPED, - WRITEABLE, - ENSURECOPY, - UPDATEIFCOPY, - FORCECAST, - - or'd (|) together - - Any of these flags present means that the returned array should - guarantee that aspect of the array. Otherwise the returned array - won't guarantee it -- it will depend on the object as to whether or - not it has such features. - - Note that ENSURECOPY is enough to guarantee CONTIGUOUS, ALIGNED, NOTSWAPPED, - and WRITEABLE and therefore it is redundant to include those as well. - - BEHAVED_FLAGS == ALIGNED | NOTSWAPPED | WRITEABLE - BEHAVED_FLAGS_RO == ALIGNED | NOTSWAPPED - CARRAY_FLAGS = CONTIGUOUS | BEHAVED_FLAGS - FARRAY_FLAGS = FORTRAN | BEHAVED_FLAGS - - By default, if the object is an array and requires is 0, - the array will just be INCREF'd and returned. - - typecode->fortran can be set to request a - fortran-contiguous array (or just | FORTRAN to the requires flags). - Fortran arrays are always behaved (aligned, - notswapped, and writeable) and not (C) CONTIGUOUS. Note that either - FORTRAN in the flag or typecode->fortran = 1 is enough to request - a FORTRAN-style array. - - UPDATEIFCOPY flag sets this flag in the returned array if a copy is - made and the base argument points to the (possibly) misbehaved array. - When the new array is deallocated, the original array held in base - is updated with the contents of the new array. This is useful, - if you don't want to deal with a possibly mis-behaved array, but want - to update it easily using a local contiguous copy. - - FORCECAST will cause a cast to occur regardless of whether or not - it is safe. - - -PyArray_Typecode structure -{ - int type_num; - int itemsize; - int fortran --- used to indicate a fortran array is desired. -} - - -Passing Data Type information to C-code -============================================ - -To get a Typecode structure from Python use the -PyArray_TypecodeConverter function. This will return a typecode -structure filled appropriately based on a wide variety of user inputs. - -See the arraymethods.c and multiarraymodule.c files for many examples of usage. - - -Getting at the structure of the array. - -You should use the #defines provided to access array structure portions: - -PyArray_DATA(obj) -PyArray_ITEMSIZE(obj) -PyArray_NDIM(obj) -PyArray_DIMS(obj) -PyArray_DIM(obj, n) -PyArray_STRIDES(obj) -PyArray_STRIDE(obj,n) - - -see more in arrayobject.h - - - -NDArray Flags -========================== - -The flags attribute of the PyArrayObject structure contains important -information about the memory used by the array (pointed to by the data member) -This flags information must be kept accurate or strange results and even -segfaults may result. - -There are 7 (binary) flags that describe the memory area used by the -data buffer. These constants are defined in arrayobject.h and -determine the bit-position of the flag. Python exposes a nice dictionary -interface for getting (and sometimes setting) these flags. - -Memory areas of all kinds can be pointed to by an NDArray, necessitating -these flags. If you get a PyArrayObject in C-code, -you should be aware of the flags that are set. -If you need to guarantee a certain kind of array -(like CONTIGUOUS and BEHAVED), then pass these requirements into the -PyArray_FromAny function. - - -CONTIGUOUS : True if the array is a (C-style) contiguous in memory. -FORTRAN : True if the array is (Fortran-style) contiguous in memory. - -Notice that 1-d arrays are always both FORTRAN contiguous and C contiguous. -Both of these flags can be checked and are convenience flags. - -OWNDATA : True if the array owns the memory (it will try and free it - using PyDataMem_FREE() on deallocation --- - so it better really own it). - -These three flags facilitate using a data pointer that is a memory-mapped -array, or part of some larger record array. But, they may have other uses... - -ALIGNED : True if the data buffer is aligned for the type. This - can be checked. -NOTSWAPPED : True if the data is in machine byte order. Arrays - can be out of machine byte order and will still - work (albeit more slowly). -WRITEABLE : True only if the data buffer can be "written" to. - - -UPDATEIFCOPY : This is a special flag that is set if this array represents - a copy made because a user required certain FLAGS in - PyArray_FromAny and a copy had to be made of some - other array. The base attribute then points to the - "misbehaved" array. When the array with this flag - set is deallocated, it will copy its contents to - the "misbehaved" array (casting if necessary). - - -PyArray_UpdateFlags(obj, FLAGS) will update the obj->flags for FLAGS - which can be any of CONTIGUOUS FORTRAN or ALIGNED. - -Some useful combinations of these flags: - -BEHAVED = ALIGNED | NOTSWAPPED | WRITEABLE -BEHAVED_RO = ALIGNED | NOTSWAPPED -CARRAY_FLAGS = CONTIGUOUS | BEHAVED -FARRAY_FLAGS = FORTRAN | BEHAVED - - -The macro PyArray_CHECKFLAGS(obj, FLAGS) can test any combination of flags. -There are several default combinations defined as macros already -(see arrayobject.h) - - - - - -There are more C-API enhancements which you can discover in the code, - or buy the book (http://www.trelgol.com) - - diff --git a/doc/DISTUTILS.txt b/doc/DISTUTILS.txt deleted file mode 100644 index cd0df60ae..000000000 --- a/doc/DISTUTILS.txt +++ /dev/null @@ -1,338 +0,0 @@ -.. -*- rest -*- - -Scipy Distutils - Users Guide -============================= - -:Author: Pearu Peterson <pearu@cens.ioc.ee> -:Discussions to: scipy-dev@scipy.org -:Created: October 2005 - -Scipy structure ---------------- - -Currently Scipy project consists of two packages: - -- Scipy core --- it provides packages like: - - + scipy.distutils - extension to Python distutils - + scipy.f2py - a tool to bind Fortran/C codes to Python - + scipy.weave - a tool to bind C++ codes to Python - + scipy.base - future replacement of Numeric and numarray packages - + etc - -- Scipy --- a collection of Scientific tools for Python. - -The aim of this document is to describe how to add new tools to Scipy. - - -Requirements for SciPy packages -------------------------------- - -Scipy consists of Python packages, called Scipy packages, that are -available to Python users via ``scipy`` name space. Each Scipy package -may contain other Scipy packages. And so on. So, Scipy directory tree -is a tree of packages with arbitrary depth and width. Any Scipy -package may depend on Scipy core packages but the dependence on other -Scipy packages should be kept minimal or zero. - -In order to add a Python package to Scipy, its building script (the -``setup.py`` file) must meet certain requirements. The minimal and the -most important one is that it must define a function -``configuration(parent_package='',top_path=None)`` that returns a -dictionary suitable for passing to ``scipy.distutils.core.setup(..)`` -function. In order to simplify the construction of such an distionary, -``scipy.distutils.misc_util`` provides a class ``Configuration``, the -usage of will be described below. - -Scipy pure Python package example ---------------------------------- - -Here follows a minimal example for a pure Python Scipy package -``setup.py`` file that will be explained in detail below:: - - #!/usr/bin/env python - def configuration(parent_package='',top_path=None): - from scipy.distutils.misc_util import Configuration - config = Configuration('mypackage',parent_package,top_path) - return config - - if __name__ == "__main__": - from scipy.distutils.core import setup - setup(**configuration(top_path='').todict()) - -The first argument ``parent_package`` of the main configuration -function will contain a name of the parent Scipy package and the -second argument ``top_path`` contains the name of the directory where -the main ``setup.py`` script is located. Both arguments should be -passed to the ``Configuration`` constructor after the name of the -current package. - -The ``Configuration`` constructor has also fourth optional argument, -``package_path``, that can be used when package files are located in -some other location than the directory of the ``setup.py`` file. - -Remaining ``Configuration`` arguments are all keyword arguments that will -be used to initialize attributes of ``Configuration`` -instance. Usually, these keywords are the same as the ones that -``setup(..)`` function would expect, for example, ``packages``, -``ext_modules``, ``data_files``, ``include_dirs``, ``libraries``, -``headers``, ``scripts``, ``package_dir``, etc. However, the direct -specification of these keywords is not recommended as the content of -these keyword arguments will not be processed or checked for the -consistency of Scipy building system. - -Finally, ``Configuration`` has ``.todict()`` method that returns all -the configuration data as a dictionary suitable for passing on to the -``setup(..)`` function. - -``Configuration`` instance attributes -------------------------------------- - -In addition to attributes that can be specified via keyword arguments -to ``Configuration`` constructor, ``Configuration`` instance (let us -denote as ``config``) has the following attributes that can be useful -in writing setup scripts: - -+ ``config.name`` - full name of the current package. The names of parent - packages can be extracted as ``config.name.split('.')``. - -+ ``config.local_path`` - path to the location of current ``setup.py`` file. - -+ ``config.top_path`` - path to the location of main ``setup.py`` file. - -``Configuration`` instance methods ----------------------------------- - -+ ``config.todict()`` --- returns configuration distionary suitable for - passing to ``scipy.distutils.core.setup(..)`` function. - -+ ``config.paths(*paths) --- applies ``glob.glob(..)`` to items of - ``paths`` if necessary. Fixes ``paths`` item that is relative to - ``config.local_path``. - -+ ``config.get_subpackage(subpackage_name,subpackage_path=None)`` --- - returns Scipy subpackage configuration. Subpackage is looked in the - current directory under the name ``subpackage_name`` but the path - can be specified also via optional ``subpackage_path`` argument. - If ``subpackage_name`` is specified as ``None`` then the subpackage - name will be taken the basename of ``subpackage_path``. - -+ ``config.add_subpackage(subpackage_name,subpackage_path=None)`` --- - add Scipy subpackage configuration to the current one. The meaning - and usage of arguments is explained above, see - ``config.get_subpackage()`` method. - -+ ``config.add_data_files(*files)`` --- prepend ``files`` to ``data_files`` - list. If ``files`` item is a tuple then its first element defines - the suffix of where data files are copied relative to package installation - directory and the second element specifies the path to data - files. By default data files are copied under package installation - directory. For example, - - :: - - config.add_data_files('foo.dat', - ('fun',['gun.dat','nun/pun.dat','/tmp/sun.dat']), - 'bar/car.dat'. - '/full/path/to/can.dat', - ) - - will install data files to the following locations:: - - <installation path of config.name package>/ - foo.dat - fun/ - gun.dat - nun/ - pun.dat - sun.dat - bar/ - car.dat - can.dat - - Path to data files can be a function taking no arguments and - returning path(s) to data files -- this is a useful when data files - are generated while building the package. (XXX: explain the step - when this function are called exactly) - -+ ``config.add_data_dir(data_path)`` --- add directory ``data_path`` - recursively to ``data_files``. The whole directory tree starting at - ``data_path`` will be copied under package installation directory. - -+ ``config.add_include_dirs(*paths)`` --- prepend ``paths`` to - ``include_dirs`` list. This list will be visible to all extension - modules of the current package. - -+ ``config.add_headers(*files)`` --- prepend ``files`` to ``headers`` - list. By default, headers will be installed under - ``<prefix>/include/pythonX.X/<config.name.replace('.','/')>/`` - directory. If ``files`` item is a tuple then it's first argument - specifies the installation suffix relative to - ``<prefix>/include/pythonX.X/`` path. - -+ ``config.add_scripts(*files)`` --- prepend ``files`` to ``scripts`` - list. Scripts will be installed under ``<prefix>/bin/`` directory. - -+ ``config.add_extension(name,sources,*kw)`` --- create and add an - ``Extension`` instance to ``ext_modules`` list. The first argument - ``name`` defines the name of the extension module that will be - installed under ``config.name`` package. The second argument is - a list of sources. ``add_extension`` method takes also keyword - arguments that are passed on to the ``Extension`` constructor. - The list of allowed keywords is the following: ``include_dirs``, - ``define_macros``, ``undef_macros``, ``library_dirs``, ``libraries``, - ``runtime_library_dirs``, ``extra_objects``, ``extra_compile_args``, - ``extra_link_args``, ``export_symbols``, ``swig_opts``, ``depends``, - ``language``, ``f2py_options``, ``module_dirs``, ``extra_info``. - - Note that ``config.paths`` method is applied to all lists that - may contain paths. ``extra_info`` is a dictionary or a list - of dictionaries that content will be appended to keyword arguments. - The list ``depends`` contains paths to files or directories - that the sources of the extension module depend on. If any path - in the ``depends`` list is newer than the extension module, then - the module will be rebuilt. - - The list of sources may contain functions ('source generators') - with a pattern ``def <funcname>(ext, build_dir): return - <source(s) or None>``. If ``funcname`` returns ``None``, no sources - are generated. And if the ``Extension`` instance has no sources - after processing all source generators, no extension module will - be built. This is the recommended way to conditionally define - extension modules. Source generator functions are called by the - ``build_src`` command of ``scipy.distutils``. - - For example, here is a typical source generator function:: - - def generate_source(ext,build_dir): - import os - from distutils.dep_util import newer - target = os.path.join(build_dir,'somesource.c') - if newer(target,__file__): - # create target file - return target - - The first argument contains the Extension instance that can be - useful to access its attributes like ``depends``, ``sources``, - etc. lists and modify them during the building process. - The second argument gives a path to a build directory that must - be used when creating files to a disk. - -+ ``config.add_library(name, sources, **build_info)`` --- add - a library to ``libraries`` list. Allowed keywords arguments - are ``depends``, ``macros``, ``include_dirs``, - ``extra_compiler_args``, ``f2py_options``. See ``.add_extension()`` - method for more information on arguments. - -+ ``config.have_f77c()`` --- return True if Fortran 77 compiler is - available (read: a simple Fortran 77 code compiled succesfully). - -+ ``config.have_f90c()`` --- return True if Fortran 90 compiler is - available (read: a simple Fortran 90 code compiled succesfully). - -+ ``config.get_version()`` --- return version string of the current package, - ``None`` if version information could not be detected. This methods - scans files ``__version__.py``, ``<packagename>_version.py``, - ``version.py``, ``__svn_version__.py`` for string variables - ``version``, ``__version__``, ``<packagename>_version``. - -+ ``config.make_svn_version_py()`` --- appends a data function to - ``data_files`` list that will generate ``__svn_version__.py`` file - to the current package directory. The file will be removed from - the source directory when Python exits. - -+ ``config.get_build_temp_dir()`` --- return a path to a temporary - directory. This is the place where one should build temporary - files. - -+ ``config.get_distribution()`` --- return distutils ``Distribution`` - instance. - -+ ``config.get_config_cmd()`` --- returns ``scipy.distutils`` config - command instance. - -Template files --------------- - -XXX: Describe how files with extensions ``.f.src``, ``.pyf.src``, -``.c.src``, etc. are pre-processed by the ``build_src`` command. - -Useful functions in ``scipy.distutils.misc_util`` -------------------------------------------------- - -+ ``get_scipy_include_dirs()`` --- return a list of Scipy base - include directories. Scipy base include directories contain - header files such as ``scipy/arrayobject.h``, ``scipy/funcobject.h`` - etc. For installed Scipy core the returned list has length 1 - but when building Scipy core the list may contain more directories, - for example, a path to ``config.h`` file that - ``scipy/base/setup.py`` file generates and is used by ``scipy`` - header files. - -+ ``append_path(prefix,path)`` --- smart append ``path`` to ``prefix``. - -+ ``def get_cmd(cmdname,_cache={})`` --- returns ``scipy.distutils`` - command instance. - -+ ``all_strings(lst)`` - -+ ``has_f_sources(sources)`` - -+ ``has_cxx_sources(sources)`` - -+ ``filter_sources(sources)`` --- return ``c_sources, cxx_sources, - f_sources, fmodule_sources`` - -+ ``get_dependencies(sources)`` - -+ ``is_local_src_dir(directory)`` - -+ ``get_ext_source_files(ext)`` - -+ ``get_script_files(scripts)`` - -+ ``get_lib_source_files(lib)`` - -+ ``get_data_files(data)`` - -+ ``dot_join(*args)`` - -+ ``get_frame(level=0)`` - -+ ``cyg2win32(path)`` - -+ ``terminal_has_colors()``, ``red_text(s)``, ``green_text(s)``, - ``yellow_text(s)``, ``blue_text(s)``, ``cyan_text(s)`` - -+ ``get_path(mod_name,parent_path=None)`` - -+ ``allpath(name)`` - -+ ``cxx_ext_match``, ``fortran_ext_match``, ``f90_ext_match``, - ``f90_module_name_match`` - -``scipy.distutils.system_info`` module --------------------------------------- - -+ ``get_info(name,notfound_action=0)`` -+ ``combine_paths(*args,**kws)`` -+ ``show_all()`` - -``scipy.distutils.cpuinfo`` module ----------------------------------- - -+ ``cpuinfo`` - -``scipy.distutils.log`` module ------------------------------- - -+ ``set_verbosity(v)`` - - -``scipy.distutils.exec_command`` module ---------------------------------------- - -+ ``get_pythonexe()`` -+ ``splitcmdline(line)`` -+ ``find_executable(exe, path=None)`` -+ ``exec_command( command, execute_in='', use_shell=None, use_tee=None, **env )`` diff --git a/doc/README.txt b/doc/README.txt deleted file mode 100644 index f63508669..000000000 --- a/doc/README.txt +++ /dev/null @@ -1,15 +0,0 @@ -Very complete documentation is available from the primary developer of -SciPy Core for a small fee. After a brief period, that documentation -will become freely available. See http://www.trelgol.com for -details. The fee and restriction period is intended to allow people -and to encourage companies to easily contribute to the development of -SciPy. - -This directory will contain all public documentation that becomes available. - -Very good documentation is also available using Python's (and -especially IPython's) own help system. Most of the functions have -docstrings that provide usage assistance. - - - |