/DLR_Main/Languages/IronPython/IronPython/Modules/Builtin.cs

/* ****************************************************************************

 *

 * Copyright (c) Microsoft Corporation. 

 *

 * This source code is subject to terms and conditions of the Apache License, Version 2.0. A 

 * copy of the license can be found in the License.html file at the root of this distribution. If 

 * you cannot locate the  Apache License, Version 2.0, please send an email to 

 * dlr@microsoft.com. By using this source code in any fashion, you are agreeing to be bound 

 * by the terms of the Apache License, Version 2.0.

 *

 * You must not remove this notice, or any other, from this software.

 *

 *

 * ***************************************************************************/



using System;

using System.Collections;

using System.Collections.Generic;

using System.Diagnostics;

using System.IO;

using System.Runtime.CompilerServices;

using System.Runtime.InteropServices;

using System.Text;

using System.Threading;



using Microsoft.Scripting;

using Microsoft.Scripting.Actions;

using Microsoft.Scripting.Runtime;

using Microsoft.Scripting.Utils;



using IronPython.Compiler;

using IronPython.Runtime;

using IronPython.Runtime.Binding;

using IronPython.Runtime.Exceptions;

using IronPython.Runtime.Operations;

using IronPython.Runtime.Types;



#if CLR2

using Microsoft.Scripting.Math;

using Complex = Microsoft.Scripting.Math.Complex64;

#else

using System.Numerics;

#endif



[assembly: PythonModule("__builtin__", typeof(IronPython.Modules.Builtin))]

namespace IronPython.Modules {

    [Documentation("")]  // Documentation suppresses XML Doc on startup.

    public static partial class Builtin {

        public const string __doc__ = "Provides access to commonly used built-in functions, exception objects, etc...";

        public const object __package__ = null;

        public const string __name__ = "__builtin__";



        public static object True {

            get {

                return ScriptingRuntimeHelpers.True;

            }

        }



        public static object False {

            get {

                return ScriptingRuntimeHelpers.False;

            }

        }



        // This will always stay null

        public static readonly object None;



        public static IronPython.Runtime.Types.Ellipsis Ellipsis {

            get {

                return IronPython.Runtime.Types.Ellipsis.Value;

            }

        }



        public static NotImplementedType NotImplemented {

            get {

                return NotImplementedType.Value;

            }

        }



        public static object exit {

            get {

                return "Use Ctrl-Z plus Return to exit";

            }

        }



        public static object quit {

            get {

                return "Use Ctrl-Z plus Return to exit";

            }

        }



        [Documentation("__import__(name) -> module\n\nImport a module.")]

        [LightThrowing]

        public static object __import__(CodeContext/*!*/ context, string name) {

            return __import__(context, name, null, null, null, -1);

        }



        [Documentation("__import__(name, globals, locals, fromlist, level) -> module\n\nImport a module.")]

        [LightThrowing]

        public static object __import__(CodeContext/*!*/ context, string name, [DefaultParameterValue(null)]object globals, [DefaultParameterValue(null)]object locals, [DefaultParameterValue(null)]object fromlist, [DefaultParameterValue(-1)]int level) {

            if (fromlist is string || fromlist is Extensible<string>) {

                fromlist = new List<object> { fromlist };

            }



            IList from = fromlist as IList;

            PythonContext pc = PythonContext.GetContext(context);



            object ret = Importer.ImportModule(context, globals, name, from != null && from.Count > 0, level);

            if (ret == null) {

                return LightExceptions.Throw(PythonOps.ImportError("No module named {0}", name));

            }



            PythonModule mod = ret as PythonModule;

            if (mod != null && from != null) {

                string strAttrName;

                for (int i = 0; i < from.Count; i++) {

                    object attrName = from[i];



                    if (pc.TryConvertToString(attrName, out strAttrName) &&

                        !String.IsNullOrEmpty(strAttrName) &&

                        strAttrName != "*") {

                        try {

                            Importer.ImportFrom(context, mod, strAttrName);

                        } catch (ImportException) {

                            continue;

                        }

                    }

                }

            }



            return ret;

        }



        [Documentation("abs(number) -> number\n\nReturn the absolute value of the argument.")]

        public static object abs(CodeContext/*!*/ context, object o) {

            if (o is int) return Int32Ops.Abs((int)o);

            if (o is long) return Int64Ops.Abs((long)o);

            if (o is double) return DoubleOps.Abs((double)o);

            if (o is bool) return (((bool)o) ? 1 : 0);



            if (o is BigInteger) return BigIntegerOps.__abs__((BigInteger)o);

            if (o is Complex) return ComplexOps.Abs((Complex)o);



            object value;

            if (PythonTypeOps.TryInvokeUnaryOperator(context, o, "__abs__", out value)) {

                return value;

            }



            throw PythonOps.TypeError("bad operand type for abs(): '{0}'", PythonTypeOps.GetName(o));

        }



        public static bool all(object x) {

            IEnumerator i = PythonOps.GetEnumerator(x);

            while (i.MoveNext()) {

                if (!PythonOps.IsTrue(i.Current)) return false;

            }

            return true;

        }



        public static bool any(object x) {

            IEnumerator i = PythonOps.GetEnumerator(x);

            while (i.MoveNext()) {

                if (PythonOps.IsTrue(i.Current)) return true;

            }

            return false;

        }



        [Documentation("apply(object[, args[, kwargs]]) -> value\n\nDeprecated.\nInstead, use:\n    function(*args, **keywords).")]

        public static object apply(CodeContext/*!*/ context, object func) {

            return PythonOps.CallWithContext(context, func);

        }



        public static object apply(CodeContext/*!*/ context, object func, object args) {

            return PythonOps.CallWithArgsTupleAndContext(context, func, ArrayUtils.EmptyObjects, args);

        }



        public static object apply(CodeContext/*!*/ context, object func, object args, object kws) {

            return context.LanguageContext.CallWithKeywords(func, args, kws);

        }



        public static PythonType basestring {

            get {

                return DynamicHelpers.GetPythonTypeFromType(typeof(string));

            }

        }



        public static string bin(int number) {

            return Int32Ops.ToBinary(number);

        }



        public static string bin(Index number) {

            return Int32Ops.ToBinary(Converter.ConvertToIndex(number));

        }



        public static string bin(BigInteger number) {

            return BigIntegerOps.ToBinary(number);

        }



        public static string bin(double number) {

            throw PythonOps.TypeError("'float' object cannot be interpreted as an index");

        }



        public static PythonType @bool {

            get {

                return DynamicHelpers.GetPythonTypeFromType(typeof(bool));

            }

        }





        public static PythonType buffer {

            get {

                return DynamicHelpers.GetPythonTypeFromType(typeof(PythonBuffer));

            }

        }



        public static PythonType bytes {

            get {

                return DynamicHelpers.GetPythonTypeFromType(typeof(Bytes));

            }

        }



        public static PythonType bytearray {

            get {

                return DynamicHelpers.GetPythonTypeFromType(typeof(ByteArray));

            }

        }



        [Documentation("callable(object) -> bool\n\nReturn whether the object is callable (i.e., some kind of function).")]

        [Python3Warning("callable() is removed in 3.x. instead call hasattr(obj, '__call__')")]

        public static bool callable(CodeContext/*!*/ context, object o) {

            return PythonOps.IsCallable(context, o);

        }



        [Documentation("chr(i) -> character\n\nReturn a string of one character with ordinal i; 0 <= i< 256.")]

        [LightThrowing]

        public static object chr(int value) {

            if (value < 0 || value > 0xFF) {

                return LightExceptions.Throw(PythonOps.ValueError("{0} is not in required range", value));

            }

            return ScriptingRuntimeHelpers.CharToString((char)value);

        }



        internal static object TryCoerce(CodeContext/*!*/ context, object x, object y) {

            PythonTypeSlot pts;

            PythonType xType = DynamicHelpers.GetPythonType(x);



            if (xType.TryResolveSlot(context, "__coerce__", out pts)) {

                object callable;

                if (pts.TryGetValue(context, x, xType, out callable)) {

                    return PythonCalls.Call(context, callable, y);

                }

            }

            return NotImplementedType.Value;

        }



        [Documentation("coerce(x, y) -> (x1, y1)\n\nReturn a tuple consisting of the two numeric arguments converted to\na common type. If coercion is not possible, raise TypeError.")]

        public static object coerce(CodeContext/*!*/ context, object x, object y) {

            object converted;



            if (x == null && y == null) {

                return PythonTuple.MakeTuple(null, null);

            }



            converted = TryCoerce(context, x, y);

            if (converted != null && converted != NotImplementedType.Value) {

                return converted;

            }



            converted = TryCoerce(context, y, x);

            if (converted != null && converted != NotImplementedType.Value) {

                PythonTuple pt = converted as PythonTuple;

                if (pt != null && pt.Count == 2) {

                    return PythonTuple.MakeTuple(pt[1], pt[0]);

                }

            }



            throw PythonOps.TypeError("coercion failed");

        }



        [Documentation("compile a unit of source code.\n\nThe source can be compiled either as exec, eval, or single.\nexec compiles the code as if it were a file\neval compiles the code as if were an expression\nsingle compiles a single statement\n\n")]

        public static object compile(CodeContext/*!*/ context, string source, string filename, string mode, [DefaultParameterValue(null)]object flags, [DefaultParameterValue(null)]object dont_inherit) {

            if (source.IndexOf('\0') != -1) {

                throw PythonOps.TypeError("compile() expected string without null bytes");

            }



            source = RemoveBom(source);



            bool inheritContext = GetCompilerInheritance(dont_inherit);

            CompileFlags cflags = GetCompilerFlags(flags);

            PythonCompilerOptions opts = GetRuntimeGeneratedCodeCompilerOptions(context, inheritContext, cflags);

            if ((cflags & CompileFlags.CO_DONT_IMPLY_DEDENT) != 0) {

                opts.DontImplyDedent = true;

            }



            SourceUnit sourceUnit;

            string unitPath = String.IsNullOrEmpty(filename) ? null : filename;



            switch (mode) {

                case "exec": sourceUnit = context.LanguageContext.CreateSnippet(source, filename, SourceCodeKind.Statements); break;

                case "eval": sourceUnit = context.LanguageContext.CreateSnippet(source, filename, SourceCodeKind.Expression); break;

                case "single": sourceUnit = context.LanguageContext.CreateSnippet(source, filename, SourceCodeKind.InteractiveCode); break;

                default:

                    throw PythonOps.ValueError("compile() arg 3 must be 'exec' or 'eval' or 'single'");

            }



            return FunctionCode.FromSourceUnit(sourceUnit, opts, true);

        }



        private static string RemoveBom(string source) {

            // skip BOM (TODO: this is ugly workaround that is in fact not strictly correct, we need binary strings to handle it correctly)

            if (source.StartsWith("\u00ef\u00bb\u00bf", StringComparison.Ordinal)) {

                source = source.Substring(3, source.Length - 3);

            }

            return source;

        }



        public static PythonType classmethod {

            get {

                return DynamicHelpers.GetPythonTypeFromType(typeof(classmethod));

            }

        }



        public static int cmp(CodeContext/*!*/ context, object x, object y) {

            return PythonOps.Compare(context, x, y);

        }



        // having a cmp overload for double would be nice, but it breaks:

        // x = 1e66666

        // y = x/x

        // cmp(y,y)

        // which returns 0 because id(y) == id(y).  If we added a double overload

        // we lose object identity.



        public static int cmp(CodeContext/*!*/ context, int x, int y) {

            return Int32Ops.Compare(x, y);

        }



        public static int cmp(CodeContext/*!*/ context, [NotNull]BigInteger x, [NotNull]BigInteger y) {

            if ((object)x == (object)y) {

                return 0;

            }

            return BigIntegerOps.Compare(x, y);

        }



        public static int cmp(CodeContext/*!*/ context, double x, [NotNull]BigInteger y) {

            return -BigIntegerOps.Compare(y, x);

        }



        public static int cmp(CodeContext/*!*/ context, [NotNull]BigInteger x, double y) {

            return BigIntegerOps.Compare(x, y);

        }



        public static int cmp(CodeContext/*!*/ context, [NotNull]string x, [NotNull]string y) {

            if ((object)x != (object)y) {

                int res = string.CompareOrdinal(x, y);

                if (res >= 1) {

                    return 1;

                } else if (res <= -1) {

                    return -1;

                }

            }



            return 0;

        }



        public static int cmp(CodeContext/*!*/ context, [NotNull]PythonTuple x, [NotNull]PythonTuple y) {

            if ((object)x == (object)y) {

                return 0;

            }

            return x.CompareTo(y);

        }



        public static PythonType complex {

            get {

                return DynamicHelpers.GetPythonTypeFromType(typeof(Complex));

            }

        }



        public static void delattr(CodeContext/*!*/ context, object o, string name) {

            PythonOps.DeleteAttr(context, o, name);

        }



        public static PythonType dict {

            get {

                return DynamicHelpers.GetPythonTypeFromType(typeof(PythonDictionary));

            }

        }



        [System.Diagnostics.CodeAnalysis.SuppressMessage("Microsoft.Design", "CA1062:ValidateArgumentsOfPublicMethods")]

        public static List dir(CodeContext/*!*/ context) {

            List res = PythonOps.MakeListFromSequence(context.Dict.Keys);



            res.sort(context);

            return res;

        }



        public static List dir(CodeContext/*!*/ context, object o) {

            IList<object> ret = PythonOps.GetAttrNames(context, o);

            List lret = new List(ret);

            lret.sort(context);

            return lret;

        }



        public static object divmod(CodeContext/*!*/ context, object x, object y) {

            Debug.Assert(NotImplementedType.Value != null);



            return PythonContext.GetContext(context).DivMod(x, y);

        }



        public static PythonType enumerate {

            get {

                return DynamicHelpers.GetPythonTypeFromType(typeof(Enumerate));

            }

        }



        public static object eval(CodeContext/*!*/ context, FunctionCode code) {

            Debug.Assert(context != null);

            if (code == null) throw PythonOps.TypeError("eval() argument 1 must be string or code object");



            return eval(context, code, null);

        }



        public static object eval(CodeContext/*!*/ context, FunctionCode code, PythonDictionary globals) {

            Debug.Assert(context != null);

            if (code == null) throw PythonOps.TypeError("eval() argument 1 must be string or code object");



            return eval(context, code, globals, globals);

        }



        public static object eval(CodeContext/*!*/ context, FunctionCode code, PythonDictionary globals, object locals) {

            Debug.Assert(context != null);

            if (code == null) throw PythonOps.TypeError("eval() argument 1 must be string or code object");



            return code.Call(GetExecEvalScopeOptional(context, globals, locals, false));

        }



        internal static PythonDictionary GetAttrLocals(CodeContext/*!*/ context, object locals) {

            PythonDictionary attrLocals = null;

            if (locals == null) {

                if (context.IsTopLevel) {

                    attrLocals = context.Dict;

                }

            } else {

                attrLocals = locals as PythonDictionary ?? new PythonDictionary(new ObjectAttributesAdapter(context, locals));

            }

            return attrLocals;

        }



        [LightThrowing]

        public static object eval(CodeContext/*!*/ context, string expression) {

            Debug.Assert(context != null);

            if (expression == null) throw PythonOps.TypeError("eval() argument 1 must be string or code object");



            return eval(context, expression, globals(context), locals(context));

        }



        [LightThrowing]

        public static object eval(CodeContext/*!*/ context, string expression, PythonDictionary globals) {

            Debug.Assert(context != null);

            if (expression == null) throw PythonOps.TypeError("eval() argument 1 must be string or code object");



            return eval(context, expression, globals, globals);

        }



        [LightThrowing]

        public static object eval(CodeContext/*!*/ context, string expression, PythonDictionary globals, object locals) {

            Debug.Assert(context != null);

            if (expression == null) throw PythonOps.TypeError("eval() argument 1 must be string or code object");



            if (locals != null && PythonOps.IsMappingType(context, locals) == ScriptingRuntimeHelpers.False) {

                throw PythonOps.TypeError("locals must be mapping");

            }



            expression = RemoveBom(expression);

            var scope = GetExecEvalScopeOptional(context, globals, locals, false);

            var pythonContext = PythonContext.GetContext(context);



            // TODO: remove TrimStart

            var sourceUnit = pythonContext.CreateSnippet(expression.TrimStart(' ', '\t'), SourceCodeKind.Expression);

            var compilerOptions = GetRuntimeGeneratedCodeCompilerOptions(context, true, 0);

            compilerOptions.Module |= ModuleOptions.LightThrow;

            compilerOptions.Module &= ~ModuleOptions.ModuleBuiltins;

            var code = FunctionCode.FromSourceUnit(sourceUnit, compilerOptions, false);



            return code.Call(scope);

        }



        public static void execfile(CodeContext/*!*/ context, object/*!*/ filename) {

            execfile(context, filename, null, null);

        }



        public static void execfile(CodeContext/*!*/ context, object/*!*/ filename, object globals) {

            execfile(context, filename, globals, null);

        }



        public static void execfile(CodeContext/*!*/ context, object/*!*/ filename, object globals, object locals) {

            if (filename == null) {

                throw PythonOps.TypeError("execfile() argument 1 must be string, not None");

            }

            

            PythonDictionary g = globals as PythonDictionary;

            if (g == null && globals != null) {

                throw PythonOps.TypeError("execfile() arg 2 must be dictionary");

            }



            PythonDictionary l = locals as PythonDictionary;

            if (l == null && locals != null) {

                throw PythonOps.TypeError("execfile() arg 3 must be dictionary");

            }



            if (l == null) {

                l = g;

            }



            var execScope = GetExecEvalScopeOptional(context, g, l, true);

            string path = Converter.ConvertToString(filename);

            PythonContext pc = PythonContext.GetContext(context);

            if (!pc.DomainManager.Platform.FileExists(path)) {

                throw PythonOps.IOError("execfile: specified file doesn't exist");

            }



            SourceUnit sourceUnit = pc.CreateFileUnit(path, pc.DefaultEncoding, SourceCodeKind.Statements);

            FunctionCode code;



            var options = GetRuntimeGeneratedCodeCompilerOptions(context, true, 0);

            //always generate an unoptimized module since we run these against a dictionary namespace

            options.Module &= ~ModuleOptions.Optimized;



            try {

                code = FunctionCode.FromSourceUnit(sourceUnit, options, false);

            } catch (UnauthorizedAccessException x) {

                throw PythonOps.IOError(x);

            }



            // Do not attempt evaluation mode for execfile

            code.Call(execScope);

        }



        public static PythonType file {

            get {

                return DynamicHelpers.GetPythonTypeFromType(typeof(PythonFile));

            }

        }



        public static string filter(CodeContext/*!*/ context, object function, [NotNull]string list) {

            if (function == null) return list;

            if (list == null) throw PythonOps.TypeError("NoneType is not iterable");



            StringBuilder sb = new StringBuilder();

            foreach (char c in list) {

                if (PythonOps.IsTrue(PythonCalls.Call(context, function, ScriptingRuntimeHelpers.CharToString(c)))) sb.Append(c);

            }



            return sb.ToString();

        }



        public static string filter(CodeContext/*!*/ context, object function, [NotNull]ExtensibleString list) {

            StringBuilder sb = new StringBuilder();

            IEnumerator e = PythonOps.GetEnumerator(list);

            while (e.MoveNext()) {

                object o = e.Current;

                object t = (function != null) ? PythonCalls.Call(context, function, o) : o;



                if (PythonOps.IsTrue(t)) {

                    sb.Append(Converter.ConvertToString(o));

                }

            }

            return sb.ToString();

        }



        /// <summary>

        /// Specialized version because enumerating tuples by Python's definition

        /// doesn't call __getitem__, but filter does!

        /// </summary>

        public static PythonTuple filter(CodeContext/*!*/ context, object function, [NotNull]PythonTuple tuple) {

            List<object> res = new List<object>(tuple.__len__());



            for (int i = 0; i < tuple.__len__(); i++) {

                object obj = tuple[i];

                object t = (function != null) ? PythonCalls.Call(context, function, obj) : obj;



                if (PythonOps.IsTrue(t)) {

                    res.Add(obj);

                }

            }



            return PythonTuple.MakeTuple(res.ToArray());

        }



        public static List filter(CodeContext/*!*/ context, object function, object list) {

            if (list == null) throw PythonOps.TypeError("NoneType is not iterable");

            List ret = new List();



            IEnumerator i = PythonOps.GetEnumerator(list);

            while (i.MoveNext()) {

                if (function == null) {

                    if (PythonOps.IsTrue(i.Current)) ret.AddNoLock(i.Current);

                } else {

                    if (PythonOps.IsTrue(PythonCalls.Call(context, function, i.Current))) ret.AddNoLock(i.Current);

                }

            }



            return ret;

        }



        public static PythonType @float {

            get {

                return DynamicHelpers.GetPythonTypeFromType(typeof(double));

            }

        }



        public static string format(CodeContext/*!*/ context, object argValue, [DefaultParameterValue("")]string formatSpec) {

            object res, formatMethod;

            OldInstance oi = argValue as OldInstance;

            if (oi != null && oi.TryGetBoundCustomMember(context, "__format__", out formatMethod)) {

                res = PythonOps.CallWithContext(context, formatMethod, formatSpec);

            } else {

                // call __format__ with the format spec (__format__ is defined on object, so this always succeeds)

                PythonTypeOps.TryInvokeBinaryOperator(

                    context,

                    argValue,

                    formatSpec,

                    "__format__",

                    out res);

            }



            string strRes = res as string;

            if (strRes == null) {

                throw PythonOps.TypeError("{0}.__format__ must return string or unicode, not {1}", PythonTypeOps.GetName(argValue), PythonTypeOps.GetName(res));

            }



            return strRes;

        }



        public static object getattr(CodeContext/*!*/ context, object o, string name) {

            return PythonOps.GetBoundAttr(context, o, name);

        }



        public static object getattr(CodeContext/*!*/ context, object o, string name, object def) {

            object ret;

            if (PythonOps.TryGetBoundAttr(context, o, name, out ret)) return ret;

            else return def;

        }



        [System.Diagnostics.CodeAnalysis.SuppressMessage("Microsoft.Design", "CA1062:ValidateArgumentsOfPublicMethods")]

        public static PythonDictionary globals(CodeContext/*!*/ context) {

            return context.ModuleContext.Globals;

        }



        public static bool hasattr(CodeContext/*!*/ context, object o, string name) {

            return PythonOps.HasAttr(context, o, name);

        }



        public static int hash(CodeContext/*!*/ context, object o) {

            return PythonContext.Hash(o);

        }



        public static int hash(CodeContext/*!*/ context, [NotNull]PythonTuple o) {

            return ((IStructuralEquatable)o).GetHashCode(PythonContext.GetContext(context).EqualityComparerNonGeneric);

        }



        // this is necessary because overload resolution selects the int form.

        public static int hash(CodeContext/*!*/ context, char o) {

            return PythonContext.Hash(o);

        }



        public static int hash(CodeContext/*!*/ context, int o) {

            return o;

        }



        public static int hash(CodeContext/*!*/ context, [NotNull]string o) {

            return o.GetHashCode();

        }



        // this is necessary because overload resolution will coerce extensible strings to strings.

        public static int hash(CodeContext/*!*/ context, [NotNull]ExtensibleString o) {

            return hash(context, (object)o);

        }



        public static int hash(CodeContext/*!*/ context, [NotNull]BigInteger o) {

            return BigIntegerOps.__hash__(o);

        }



        public static int hash(CodeContext/*!*/ context, [NotNull]Extensible<BigInteger> o) {

            return hash(context, (object)o);

        }



        public static int hash(CodeContext/*!*/ context, double o) {

            return DoubleOps.__hash__(o);

        }



        public static void help(CodeContext/*!*/ context, object o) {

            StringBuilder doc = new StringBuilder();

            List<object> doced = new List<object>();  // document things only once



            help(context, doced, doc, 0, o);



            if (doc.Length == 0) {

                if (!(o is string)) {

                    help(context, DynamicHelpers.GetPythonType(o));

                    return;

                }

                doc.Append("no documentation found for ");

                doc.Append(PythonOps.Repr(context, o));

            }



            string[] strings = doc.ToString().Split('\n');

            for (int i = 0; i < strings.Length; i++) {

                /* should read only a key, not a line, but we don't seem

                 * to have a way to do that...

                if ((i % Console.WindowHeight) == 0) {

                    Ops.Print(context.SystemState, "-- More --");

                    Ops.ReadLineFromSrc(context.SystemState);

                }*/

                PythonOps.Print(context, strings[i]);

            }

        }



        private static void help(CodeContext/*!*/ context, List<object>/*!*/ doced, StringBuilder/*!*/ doc, int indent, object obj) {

            PythonType type;

            BuiltinFunction builtinFunction;

            PythonFunction function;

            BuiltinMethodDescriptor methodDesc;

            Method method;

            string strVal;

            PythonModule pyModule;

            OldClass oldClass;



            if (doced.Contains(obj)) return;  // document things only once

            doced.Add(obj);



            if ((strVal = obj as string) != null) {

                if (indent != 0) return;



                // try and find things that string could refer to,

                // then call help on them.

                foreach (object module in PythonContext.GetContext(context).SystemStateModules.Values) {

                    IList<object> attrs = PythonOps.GetAttrNames(context, module);

                    List candidates = new List();

                    foreach (string s in attrs) {

                        if (s == strVal) {

                            object modVal;

                            if (!PythonOps.TryGetBoundAttr(context, module, strVal, out modVal))

                                continue;



                            candidates.append(modVal);

                        }

                    }



                    // favor types, then built-in functions, then python functions,

                    // and then only display help for one.

                    type = null;

                    builtinFunction = null;

                    function = null;

                    for (int i = 0; i < candidates.__len__(); i++) {

                        if ((type = candidates[i] as PythonType) != null) {

                            break;

                        }



                        if (builtinFunction == null && (builtinFunction = candidates[i] as BuiltinFunction) != null)

                            continue;



                        if (function == null && (function = candidates[i] as PythonFunction) != null)

                            continue;

                    }



                    if (type != null) help(context, doced, doc, indent, type);

                    else if (builtinFunction != null) help(context, doced, doc, indent, builtinFunction);

                    else if (function != null) help(context, doced, doc, indent, function);

                }

            } else if ((type = obj as PythonType) != null) {

                // find all the functions, and display their 

                // documentation                

                if (indent == 0) {

                    doc.AppendFormat("Help on {0} in module {1}\n\n", type.Name, PythonOps.GetBoundAttr(context, type, "__module__"));

                }



                PythonTypeSlot dts;

                if (type.TryResolveSlot(context, "__doc__", out dts)) {

                    object docText;

                    if (dts.TryGetValue(context, null, type, out docText) && docText != null)

                        AppendMultiLine(doc, docText.ToString() + Environment.NewLine, indent);

                    AppendIndent(doc, indent);

                    doc.AppendLine("Data and other attributes defined here:");

                    AppendIndent(doc, indent);

                    doc.AppendLine();

                }



                List names = type.GetMemberNames(context);

                names.sort(context);



                foreach (string name in names) {

                    if (name == "__class__") continue;



                    PythonTypeSlot value;

                    object val;

                    if (type.TryLookupSlot(context, name, out value) &&

                        value.TryGetValue(context, null, type, out val)) {

                        help(context, doced, doc, indent + 1, val);

                    }

                }

            } else if ((methodDesc = obj as BuiltinMethodDescriptor) != null) {

                if (indent == 0) doc.AppendFormat("Help on method-descriptor {0}\n\n", methodDesc.__name__);

                AppendIndent(doc, indent);

                doc.Append(methodDesc.__name__);

                doc.Append("(...)\n");



                AppendMultiLine(doc, methodDesc.__doc__, indent + 1);

            } else if ((builtinFunction = obj as BuiltinFunction) != null) {

                if (indent == 0) doc.AppendFormat("Help on built-in function {0}\n\n", builtinFunction.Name);

                AppendIndent(doc, indent);

                doc.Append(builtinFunction.Name);

                doc.Append("(...)\n");



                AppendMultiLine(doc, builtinFunction.__doc__, indent + 1);

            } else if ((function = obj as PythonFunction) != null) {

                if (indent == 0) doc.AppendFormat("Help on function {0} in module {1}:\n\n", function.__name__, function.__module__);



                AppendIndent(doc, indent);

                doc.Append(function.GetSignatureString());

                string pfDoc = Converter.ConvertToString(function.__doc__);

                if (!String.IsNullOrEmpty(pfDoc)) {

                    AppendMultiLine(doc, pfDoc, indent);

                }

            } else if ((method = obj as Method) != null && ((function = method.im_func as PythonFunction) != null)) {

                if (indent == 0) doc.AppendFormat("Help on method {0} in module {1}:\n\n", function.__name__, function.__module__);



                AppendIndent(doc, indent);

                doc.Append(function.GetSignatureString());



                if (method.im_self == null) {

                    doc.AppendFormat(" unbound {0} method\n", PythonOps.ToString(method.im_class));

                } else {

                    doc.AppendFormat(" method of {0} instance\n", PythonOps.ToString(method.im_class));

                }



                string pfDoc = Converter.ConvertToString(function.__doc__);

                if (!String.IsNullOrEmpty(pfDoc)) {

                    AppendMultiLine(doc, pfDoc, indent);

                }

            } else if ((pyModule = obj as PythonModule) != null) {

                foreach (string name in pyModule.__dict__.Keys) {

                    if (name == "__class__" || name == "__builtins__") continue;



                    object value;

                    if (pyModule.__dict__.TryGetValue(name, out value)) {

                        help(context, doced, doc, indent + 1, value);

                    }

                }

            } else if ((oldClass = obj as OldClass) != null) {

                if (indent == 0) {

                    doc.AppendFormat("Help on {0} in module {1}\n\n", oldClass.Name, PythonOps.GetBoundAttr(context, oldClass, "__module__"));

                }



                object docText;

                if (oldClass.TryLookupSlot("__doc__", out docText) && docText != null) {

                    AppendMultiLine(doc, docText.ToString() + Environment.NewLine, indent);

                    AppendIndent(doc, indent);

                    doc.AppendLine("Data and other attributes defined here:");

                    AppendIndent(doc, indent);

                    doc.AppendLine();

                }



                IList<object> names = ((IPythonMembersList)oldClass).GetMemberNames(context);

                List sortNames = new List(names);

                sortNames.sort(context);

                names = sortNames;

                foreach (string name in names) {

                    if (name == "__class__") continue;



                    object value;



                    if (oldClass.TryLookupSlot(name, out value))

                        help(context, doced, doc, indent + 1, value);

                }

            }

        }



        private static void AppendMultiLine(StringBuilder doc, string multiline, int indent) {

            string[] docs = multiline.Split('\n');

            for (int i = 0; i < docs.Length; i++) {

                AppendIndent(doc, indent + 1);

                doc.Append(docs[i]);

                doc.Append('\n');

            }

        }



        private static void AppendIndent(StringBuilder doc, int indent) {

            doc.Append(" |  ");

            for (int i = 0; i < indent; i++) doc.Append("    ");

        }



        //??? type this to string

        public static object hex(object o) {

            return PythonOps.Hex(o);

        }



        public static object id(object o) {

            long res = PythonOps.Id(o);

            if (PythonOps.Id(o) <= Int32.MaxValue) {

                return (int)res;

            }

            return (BigInteger)res;

        }



        [LightThrowing]

        public static object input(CodeContext/*!*/ context) {

            return input(context, null);

        }



        [LightThrowing]

        public static object input(CodeContext/*!*/ context, object prompt) {

            return eval(context, raw_input(context, prompt));

        }



        public static PythonType @int {

            get {

                return DynamicHelpers.GetPythonTypeFromType(typeof(int));

            }

        }



        public static string intern(object o) {

            string s = o as string;

            if (s == null) {

                throw PythonOps.TypeError("intern: argument must be string");

            }

            return string.Intern(s);

        }



        public static bool isinstance(object o, [NotNull]PythonType typeinfo) {

            return PythonOps.IsInstance(o, typeinfo);

        }



        public static bool isinstance(CodeContext context, object o, [NotNull]PythonTuple typeinfo) {

            return PythonOps.IsInstance(context, o, typeinfo);

        }



        public static bool isinstance(CodeContext context, object o, object typeinfo) {

            return PythonOps.IsInstance(context, o, typeinfo);

        }



        public static bool issubclass(CodeContext context, [NotNull]OldClass c, object typeinfo) {

            return PythonOps.IsSubClass(context, c.TypeObject, typeinfo);

        }



        public static bool issubclass(CodeContext context, [NotNull]PythonType c, object typeinfo) {

            return PythonOps.IsSubClass(context, c, typeinfo);

        }



        public static bool issubclass(CodeContext context, [NotNull]PythonType c, [NotNull]PythonType typeinfo) {

            return PythonOps.IsSubClass(c, typeinfo);

        }



        [LightThrowing]

        public static object issubclass(CodeContext/*!*/ context, object o, object typeinfo) {

            PythonTuple pt = typeinfo as PythonTuple;

            if (pt != null) {

                // Recursively inspect nested tuple(s)

                foreach (object subTypeInfo in pt) {

                    try {

                        PythonOps.FunctionPushFrame(PythonContext.GetContext(context));

                        var res = issubclass(context, o, subTypeInfo);

                        if (res == ScriptingRuntimeHelpers.True) {

                            return ScriptingRuntimeHelpers.True;

                        } else if (LightExceptions.IsLightException(res)) {

                            return res;

                        }

                    } finally {

                        PythonOps.FunctionPopFrame();

                    }

                }

                return ScriptingRuntimeHelpers.False;

            }



            object bases;

            PythonTuple tupleBases;



            if (!PythonOps.TryGetBoundAttr(o, "__bases__", out bases) || (tupleBases = bases as PythonTuple) == null) {

                return LightExceptions.Throw(PythonOps.TypeError("issubclass() arg 1 must be a class"));

            }



            foreach (object baseCls in tupleBases) {

                PythonType pyType;

                OldClass oc;



                if (baseCls == typeinfo) {

                    return ScriptingRuntimeHelpers.True;

                } else if ((pyType = baseCls as PythonType) != null) {

                    if (issubclass(context, pyType, typeinfo)) {

                        return ScriptingRuntimeHelpers.True;

                    }

                } else if ((oc = baseCls as OldClass) != null) {

                    if (issubclass(context, oc, typeinfo)) {

                        return ScriptingRuntimeHelpers.True;

                    }

                } else if (hasattr(context, baseCls, "__bases__")) {

                    var res = issubclass(context, baseCls, typeinfo);

                    if (res == ScriptingRuntimeHelpers.True) {

                        return ScriptingRuntimeHelpers.True;

                    } else if (LightExceptions.IsLightException(res)) {

                        return res;

                    }

                }

            }



            return ScriptingRuntimeHelpers.False;

        }



        public static object iter(CodeContext/*!*/ context, object o) {

            return PythonOps.GetEnumeratorObject(context, o);

        }



        public static object iter(CodeContext/*!*/ context, object func, object sentinel) {

            if (!PythonOps.IsCallable(context, func)) {

                throw PythonOps.TypeError("iter(v, w): v must be callable");

            }

            return new SentinelIterator(context, func, sentinel);

        }



        public static int len([NotNull]string/*!*/ str) {

            return str.Length;

        }



        public static int len([NotNull]ExtensibleString/*!*/ str) {

            return str.__len__();

        }



        public static int len([NotNull]List/*!*/ list) {

            return list.__len__();

        }



        public static int len([NotNull]PythonTuple/*!*/ tuple) {

            return tuple.__len__();

        }



        public static int len([NotNull]PythonDictionary/*!*/ dict) {

            return dict.__len__();

        }



        public static int len([NotNull]ICollection/*!*/ collection) {

            return collection.Count;

        }



        public static int len(object o) {

            return PythonOps.Length(o);

        }



        public static PythonType set {

            get {

                return DynamicHelpers.GetPythonTypeFromType(typeof(SetCollection));

            }

        }



        public static PythonType frozenset {

            get {

                return DynamicHelpers.GetPythonTypeFromType(typeof(FrozenSetCollection));

            }

        }



        public static PythonType list {

            get {

                return DynamicHelpers.GetPythonTypeFromType(typeof(List));

            }

        }



        [System.Diagnostics.CodeAnalysis.SuppressMessage("Microsoft.Design", "CA1062:ValidateArgumentsOfPublicMethods")]

        public static object locals(CodeContext/*!*/ context) {

            PythonDictionary dict = context.Dict;

            ObjectAttributesAdapter adapter = dict._storage as ObjectAttributesAdapter;

            if (adapter != null) {

                // we've wrapped Locals in an PythonDictionary, give the user back the

                // original object.

                return adapter.Backing;

            }



            return context.Dict;

        }



        public static PythonType @long {

            get {

                return TypeCache.BigInteger;

            }

        }



        private static CallSite<Func<CallSite, CodeContext, T, T1, object>> MakeMapSite<T, T1>(CodeContext/*!*/ context) {

            return CallSite<Func<CallSite, CodeContext, T, T1, object>>.Create(

                PythonContext.GetContext(context).InvokeOne

            );

        }



        public static List map(CodeContext/*!*/ context, object func, [NotNull]IEnumerable enumerator) {

            IEnumerator en = PythonOps.GetEnumerator(enumerator);

            

            List ret = new List();            

            CallSite<Func<CallSite, CodeContext, object, object, object>> mapSite = null;



            if (func != null) {

                mapSite = MakeMapSite<object, object>(context);

            }



            while (en.MoveNext()) {

                if (func == null) {

                    ret.AddNoLock(en.Current);

                } else {

                    ret.AddNoLock(mapSite.Target(mapSite, context, func, en.Current));

                }

            }

        

            return ret;

        }



        public static List map(

            CodeContext/*!*/ context,

            SiteLocalStorage<CallSite<Func<CallSite, CodeContext, object, object, object>>> storage,

            object func,

            [NotNull]string enumerator

        ) {

            CallSite<Func<CallSite, CodeContext, object, object, object>> mapSite;

            if (storage.Data == null && func != null) {

                storage.Data = MakeMapSite<object, object>(context);

            }

            mapSite = storage.Data;



            List ret = new List(enumerator.Length);

            foreach (char o in enumerator) {

                if (func == null) {

                    ret.AddNoLock(ScriptingRuntimeHelpers.CharToString(o));

                } else {

                    ret.AddNoLock(mapSite.Target(mapSite, context, func, ScriptingRuntimeHelpers.CharToString(o)));

                }

            }



            return ret;

        }



        public static List map(

            CodeContext/*!*/ context,

            SiteLocalStorage<CallSite<Func<CallSite, CodeContext, PythonType, object, object>>> storage,

            [NotNull]PythonType/*!*/ func,

            [NotNull]string enumerator

        ) {

            CallSite<Func<CallSite, CodeContext, PythonType, string, object>> mapSite = MakeMapSite<PythonType, string>(context);



            List ret = new List(enumerator.Length);

            foreach (char o in enumerator) {

                ret.AddNoLock(mapSite.Target(mapSite, context, func, ScriptingRuntimeHelpers.CharToString(o)));

            }

            return ret;

        }



        public static List map(

            CodeContext/*!*/ context,

            SiteLocalStorage<CallSite<Func<CallSite, CodeContext, PythonType, object, object>>> storage,

            [NotNull]PythonType/*!*/ func,

            [NotNull]IEnumerable enumerator

        ) {

            CallSite<Func<CallSite, CodeContext, PythonType, object, object>> mapSite;

            if (storage.Data == null) {

                storage.Data = MakeMapSite<PythonType, object>(context);

            }

            mapSite = storage.Data;



            IEnumerator en = PythonOps.GetEnumerator(enumerator);

            List ret = new List();

            while (en.MoveNext()) {

                ret.AddNoLock(mapSite.Target(mapSite, context, func, en.Current));

            }

            return ret;

        }



        public static List map(

            CodeContext/*!*/ context,

            SiteLocalStorage<CallSite<Func<CallSite, CodeContext, BuiltinFunction, object, object>>> storage,

            [NotNull]BuiltinFunction/*!*/ func,

            [NotNull]string enumerator

        ) {

            CallSite<Func<CallSite, CodeContext, BuiltinFunction, object, object>> mapSite;

            if (storage.Data == null) {

                storage.Data = MakeMapSite<BuiltinFunction, object>(context);

            }

            mapSite = storage.Data;



            List ret = new List(enumerator.Length);

            foreach (char o in enumerator) {

                ret.AddNoLock(mapSite.Target(mapSite, context, func, ScriptingRuntimeHelpers.CharToString(o)));

            }

            return ret;

        }



        public static List map(

            CodeContext/*!*/ context,

            SiteLocalStorage<CallSite<Func<CallSite, CodeContext, BuiltinFunction, object, object>>> storage,

            [NotNull]BuiltinFunction/*!*/ func,

            [NotNull]IEnumerable enumerator

        ) {

            CallSite<Func<CallSite, CodeContext, BuiltinFunction, object, object>> mapSite;

            if (storage.Data == null) {

                storage.Data = MakeMapSite<BuiltinFunction, object>(context);

            }

            mapSite = storage.Data;



            IEnumerator en = PythonOps.GetEnumerator(enumerator);

            List ret = new List();

            while (en.MoveNext()) {

                ret.AddNoLock(mapSite.Target(mapSite, context, func, en.Current));

            }

            return ret;

        }



        public static List map(

            CodeContext/*!*/ context,

            SiteLocalStorage<CallSite<Func<CallSite, C