From de5d66366e4e4d5c0cee324c99097cb72cb141ac Mon Sep 17 00:00:00 2001 From: Lamparter Date: Sun, 17 Nov 2024 13:15:38 +0000 Subject: [PATCH 01/26] Simplify root directory --- CONTRIBUTING.md => .github/CONTRIBUTING.md | 0 README.md => .github/README.md | 0 2 files changed, 0 insertions(+), 0 deletions(-) rename CONTRIBUTING.md => .github/CONTRIBUTING.md (100%) rename README.md => .github/README.md (100%) diff --git a/CONTRIBUTING.md b/.github/CONTRIBUTING.md similarity index 100% rename from CONTRIBUTING.md rename to .github/CONTRIBUTING.md diff --git a/README.md b/.github/README.md similarity index 100% rename from README.md rename to .github/README.md From 51cab0900da3e85e3eb89c9f3c33c2a6591a0521 Mon Sep 17 00:00:00 2001 From: Lamparter Date: Sun, 17 Nov 2024 13:15:51 +0000 Subject: [PATCH 02/26] Remove Markdown issue template --- .github/ISSUE_TEMPLATE.md | 39 --------------------------------------- 1 file changed, 39 deletions(-) delete mode 100644 .github/ISSUE_TEMPLATE.md diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md deleted file mode 100644 index c235ec2f6..000000000 --- a/.github/ISSUE_TEMPLATE.md +++ /dev/null @@ -1,39 +0,0 @@ -### Prerequisites - -The issue tracker is used to report bugs and request new features, **NOT** to ask questions. - -Questions should be posted in [Discussions](https://github.com/IronLanguages/ironpython3/discussions/categories/q-a) or to the users mailing list which can be accessed at -https://ironpython.groups.io/g/users. - -* [ ] Are you running the latest version? -* [ ] Are you reporting to the correct repository? -* [ ] Did you perform a cursory search? - -### Description - -[Description of the bug or feature] - -### Steps to Reproduce - -1. [First Step] -2. [Second Step] -3. [and so on...] - -**Expected behavior:** - -[What you expected to happen] - -**Actual behavior:** - -[What actually happened] - -### Version Information - -If you are using the `ipy` console program, provide output of executing `ipy -VV`. If it is a local build, provide also the git hash of the commit used to build IronPython. In either case, provide the type of the operating system used. - -If you are using the IronPython engine embedded in a .NET application, provide the version number of the NuGet package used (or if it is a local build, the git hash of the commit used to build IronPython), and the following info: - -* .NET platform used (choice from: .NET, .NET Core, .NET Framework, Mono, Unity, Xamarin), -* Version of the .NET platform used, -* Operating system used, -* Value of `sys.version`, from imported module `sys`. From f6b721b34d68ddcc0842ce534d00602784f6b5ee Mon Sep 17 00:00:00 2001 From: Lamparter Date: Sun, 17 Nov 2024 13:18:14 +0000 Subject: [PATCH 03/26] Rename `LICENSE` to `LICENSE.md` --- LICENSE => LICENSE.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename LICENSE => LICENSE.md (100%) diff --git a/LICENSE b/LICENSE.md similarity index 100% rename from LICENSE rename to LICENSE.md From 403b7e3c4f5bfd5bff38ba1c111d1f948892ab20 Mon Sep 17 00:00:00 2001 From: Lamparter Date: Sun, 17 Nov 2024 14:13:02 +0000 Subject: [PATCH 04/26] Migrate "what's new" documents to GitHub Wiki --- WhatsNewInPython30.md | 158 ----------------------------------------- WhatsNewInPython31.md | 42 ----------- WhatsNewInPython32.md | 128 ---------------------------------- WhatsNewInPython33.md | 141 ------------------------------------- WhatsNewInPython34.md | 143 ------------------------------------- WhatsNewInPython35.md | 154 ---------------------------------------- WhatsNewInPython36.md | 159 ------------------------------------------ 7 files changed, 925 deletions(-) delete mode 100644 WhatsNewInPython30.md delete mode 100644 WhatsNewInPython31.md delete mode 100644 WhatsNewInPython32.md delete mode 100644 WhatsNewInPython33.md delete mode 100644 WhatsNewInPython34.md delete mode 100644 WhatsNewInPython35.md delete mode 100644 WhatsNewInPython36.md diff --git a/WhatsNewInPython30.md b/WhatsNewInPython30.md deleted file mode 100644 index 24530cbcd..000000000 --- a/WhatsNewInPython30.md +++ /dev/null @@ -1,158 +0,0 @@ -# What's New In Python 3.0 - -https://docs.python.org/3/whatsnew/3.0.html - -Views And Iterators Instead Of Lists -======================= -- [x] `dict` methods `dict.keys()`, `dict.items()` and `dict.values()` return "views" instead of lists. For example, this no longer works: `k = d.keys(); k.sort()`. Use `k = sorted(d)` instead (this works in Python 2.5 too and is just as efficient). -- [x] Also, the `dict.iterkeys()`, `dict.iteritems()` and `dict.itervalues()` methods are no longer supported. -- [x] `map()` and `filter()` return iterators. If you really need a list, a quick fix is e.g. `list(map(...))`, but a better fix is often to use a list comprehension (especially when the original code uses lambda), or rewriting the code so it doesn't need a list at all. Particularly tricky is `map()` invoked for the side effects of the function; the correct transformation is to use a regular for loop (since creating a list would just be wasteful). -- [x] `zip()` now returns an iterator. - -Ordering Comparisons -============== -- [x] The ordering comparison operators (`<`, `<=`, `>=`, `>`) raise a `TypeError` exception when the operands don't have a meaningful natural ordering. Thus, expressions like `1 < ''`, `0 > None` or `len <= len` are no longer valid, and e.g. `None < None` raises `TypeError` instead of returning `False`. A corollary is that sorting a heterogeneous list no longer makes sense - all the elements must be comparable to each other. Note that this does not apply to the `==` and `!=` operators: objects of different incomparable types always compare unequal to each other. -- [x] `builtin.sorted()` and `list.sort()` no longer accept the `cmp` argument providing a comparison function. Use the `key` argument instead. N.B. the `key` and `reverse` arguments are now "keyword-only" -- [x] The `cmp()` function should be treated as gone, and the `__cmp__()` special method is no longer supported. Use `__lt__()` for sorting, `__eq__()` with `__hash__()`, and other rich comparisons as needed. (If you really need the `cmp()` functionality, you could use the expression `(a > b) - (a < b)` as the equivalent for` cmp(a, b)`.) - -Integers -===== -- [x] [PEP 0237][]: Essentially, `long` renamed to `int`. That is, there is only one built-in integral type, named `int`; but it behaves mostly like the old `long` type. -- [x] [PEP 0238][]: An expression like `1/2` returns a `float`. Use `1//2` to get the truncating behavior. (The latter syntax has existed for years, at least since Python 2.2.) -- [x] The `sys.maxint` constant was removed, since there is no longer a limit to the value of integers. However, `sys.maxsize` can be used as an integer larger than any practical list or string index. It conforms to the implementation's "natural" integer size and is typically the same as `sys.maxint` in previous releases on the same platform (assuming the same build options). -- [x] The `repr()` of a `long` integer doesn't include the trailing `L` anymore, so code that unconditionally strips that character will chop off the last digit instead. (Use `str()` instead.) -- [x] Octal literals are no longer of the form `0720`; use `0o720` instead. - -Text Vs. Data Instead Of Unicode Vs. 8-bit -=========================== -- [x] Python 3.0 uses the concepts of text and (binary) data instead of Unicode strings and 8-bit strings. All text is Unicode; however encoded Unicode is represented as binary data. The type used to hold text is `str`, the type used to hold data is `bytes`. The biggest difference with the 2.x situation is that any attempt to mix text and data in Python 3.0 raises `TypeError`, whereas if you were to mix Unicode and 8-bit strings in Python 2.x, it would work if the 8-bit string happened to contain only 7-bit (ASCII) bytes, but you would get `UnicodeDecodeError` if it contained non-ASCII values. This value-specific behavior has caused numerous sad faces over the years. -- [ ] As a consequence of this change in philosophy, pretty much all code that uses Unicode, encodings or binary data most likely has to change. The change is for the better, as in the 2.x world there were numerous bugs having to do with mixing encoded and unencoded text. To be prepared in Python 2.x, start using `unicode` for all unencoded text, and `str` for binary or encoded data only. Then the `2to3` tool will do most of the work for you. -- [x] ~~You can no longer use `u"..."` literals for Unicode text.~~ (Readded in Python 3.3). However, you must use `b"..."` literals for binary data. -- [x] As the `str` and `bytes` types cannot be mixed, you must always explicitly convert between them. Use `str.encode()` to go from `str` to `bytes`, and `bytes.decode()` to go from `bytes` to `str`. You can also use `bytes(s, encoding=...)` and `str(b, encoding=...)`, respectively. -- [x] Like `str`, the `bytes` type is immutable. There is a separate mutable type to hold buffered binary data, `bytearray`. Nearly all APIs that accept `bytes` also accept `bytearray`. The mutable API is based on `collections.MutableSequence`. -- [x] All backslashes in raw string literals are interpreted literally. This means that `'\U'` and `'\u'` escapes in raw strings are not treated specially. For example, `r'\u20ac'` is a string of 6 characters in Python 3.0, whereas in 2.6, `ur'\u20ac'` was the single "euro" character. (Of course, this change only affects raw string literals; the euro character is `'\u20ac'` in Python 3.0.) -- [x] The builtin `basestring` abstract type was removed. Use `str` instead. The `str` and `bytes` types don't have functionality enough in common to warrant a shared base class. The `2to3` tool (see below) replaces every occurrence of `basestring` with `str`. -- [ ] Files opened as text files (still the default mode for `open()`) always use an encoding to map between strings (in memory) and bytes (on disk). Binary files (opened with a `b` in the mode argument) always use bytes in memory. This means that if a file is opened using an incorrect mode or encoding, I/O will likely fail loudly, instead of silently producing incorrect data. It also means that even Unix users will have to specify the correct mode (text or binary) when opening a file. There is a platform-dependent default encoding, which on Unixy platforms can be set with the `LANG` environment variable (and sometimes also with some other platform-specific locale-related environment variables). In many cases, but not all, the system default is UTF-8; you should never count on this default. Any application reading or writing more than pure ASCII text should probably have a way to override the encoding. There is no longer any need for using the encoding-aware streams in the `codecs` module. -- [ ] Filenames are passed to and returned from APIs as (Unicode) strings. This can present platform-specific problems because on some platforms filenames are arbitrary byte strings. (On the other hand, on Windows filenames are natively stored as Unicode.) As a work-around, most APIs (e.g. `open()` and many functions in the `os` module) that take filenames accept bytes objects as well as strings, and a few APIs have a way to ask for a `bytes` return value. Thus, `os.listdir()` returns a list of `bytes` instances if the argument is a `bytes` instance, and `os.getcwdb()` returns the current working directory as a `bytes` instance. Note that when `os.listdir()` returns a list of strings, filenames that cannot be decoded properly are omitted rather than raising `UnicodeError`. -- [ ] Some system APIs like `os.environ` and `sys.argv` can also present problems when the bytes made available by the system is not interpretable using the default encoding. Setting the `LANG` variable and rerunning the program is probably the best approach. -- [x] [PEP 3138][]: The `repr()` of a string no longer escapes non-ASCII characters. It still escapes control characters and code points with non-printable status in the Unicode standard, however. -- [x] [PEP 3120][]: The default source encoding is now UTF-8. -- [x] [PEP 3131][]: Non-ASCII letters are now allowed in identifiers. (However, the standard library remains ASCII-only with the exception of contributor names in comments.) -- [x] The `StringIO` and `cStringIO` modules are gone. Instead, import the `io` module and use `io.StringIO` or `io.BytesIO` for text and data respectively. - - -New Syntax -======== -- [x] [PEP 3107][]: Function argument and return value annotations. This provides a standardized way of annotating a function's parameters and return value. There are no semantics attached to such annotations except that they can be introspected at runtime using the `__annotations__` attribute. The intent is to encourage experimentation through metaclasses, decorators or frameworks. -- [ ] [PEP 3102][]: Keyword-only arguments. Named parameters occurring after `*args` in the parameter list must be specified using keyword syntax in the call. You can also use a bare `*` in the parameter list to indicate that you don't accept a variable-length argument list, but you do have keyword-only arguments. -- [x] Keyword arguments are allowed after the list of base classes in a class definition. This is used by the new convention for specifying a metaclass (see next section), but can be used for other purposes as well, as long as the metaclass supports it. -- [x] [PEP 3104][]: `nonlocal` statement. Using `nonlocal x` you can now assign directly to a variable in an outer (but non-`global`) scope. `nonlocal` is a new reserved word. -- [x] [PEP 3132][]: Extended Iterable Unpacking. You can now write things like `a, b, *rest = some_sequence`. And even `*rest, a = stuff`. The `rest` object is always a (possibly empty) list; the right-hand side may be any iterable -- [x] Dictionary comprehensions: `{k: v for k, v in stuff}` means the same thing as `dict(stuff)` but is more flexible. (This is [PEP 0274][] vindicated. :-) -- [x] Set literals, e.g. `{1, 2}`. Note that `{}` is an empty dictionary; use `set()` for an empty set. Set comprehensions are also supported; e.g., `{x for x in stuff}` means the same thing as `set(stuff)` but is more flexible. -- [x] New octal literals, e.g. `0o720` (already in 2.6). The old octal literals (`0720`) are gone. -- [x] New binary literals, e.g. `0b1010` (already in 2.6), and there is a new corresponding builtin function, `bin()`. -- [x] Bytes literals are introduced with a leading `b` or `B`, and there is a new corresponding builtin function, `bytes()`. - -Changed Syntax -========== -- [x] [PEP 3109][] and [PEP 3134][]: new `raise` statement syntax: `raise [expr [from expr]]`. -- [x] `as` and `with` are now reserved words. (Since 2.6, actually.) -- [x] `True`, `False`, and `None` are reserved words. (2.6 partially enforced the restrictions on `None` already.) -- [x] Change from `except exc, var` to `except exc as var`. See [PEP 3110][] -- [x] [PEP 3115][]: New Metaclass Syntax -- [x] List comprehensions no longer support the syntactic form `[... for var in item1, item2, ...]`. Use `[... for var in (item1, item2, ...)]` instead. -- [x] The ellipsis (`...`) can be used as an atomic expression anywhere. (Previously it was only allowed in slices.) Also, it must now be spelled as `...`. (Previously it could also be spelled as `. . .`, by a mere accident of the grammar.) - -Removed Syntax -=========== -- [x] [PEP 3113][]: Tuple parameter unpacking removed. You can no longer write `def foo(a, (b, c)): ....` Use `def foo(a, b_c): b, c = b_c` instead. -- [x] Removed backticks (use `repr()` instead). -- [x] Removed `<>` (use `!=` instead). -- [x] Removed keyword: `exec()` is no longer a keyword; it remains as a function -- [x] Integer literals no longer support a trailing `l` or `L`. -- [x] ~~String literals no longer support a leading `u` or `U`.~~ (Readded in Python 3.3) -- [x] The `from module import *` syntax is only allowed at the module level, no longer inside functions. -- [x] The only acceptable syntax for relative imports is `from .[module] import name`. All import forms not starting with `.` are interpreted as absolute imports. ([PEP 0328][]) -- [x] Classic classes are gone. - -Library Changes -========== -- [x] `_winreg` renamed to `winreg` -- [x] `copy_reg` renamed to `copyreg` -- [x] Cleanup of the `sys` module: removed `sys.exitfunc()`, `sys.exc_clear()`, `sys.exc_type`, `sys.exc_value`, `sys.exc_traceback`. -- [x] Cleanup of the `array.array` type: the `read()` and `write()` methods are gone; use `fromfile()` and `tofile()` instead. Also, the `'c'` typecode for array is gone - use either `'b'` for bytes or `'u'` for Unicode characters. -- [x] Cleanup of the operator module: removed `sequenceIncludes()` and `isCallable()`. -- [x] Cleanup of the `thread` module: `acquire_lock()` and `release_lock()` are gone; use `acquire()` and `release()` instead. -- [x] Cleanup of the `random` module: removed the `jumpahead()` API. -- [x] The functions `os.tmpnam()`, `os.tempnam()` and `os.tmpfile()` have been removed in favor of the `tempfile` module. -- [x] `string.letters` and its friends (`string.lowercase` and `string.uppercase`) are gone. Use `string.ascii_letters` etc. instead. (The reason for the removal is that `string.letters` and friends had locale-specific behavior, which is a bad idea for such attractively-named global "constants".) - -[PEP 3101][]: A New Approach To String Formatting -====================== -- [x] A new system for built-in string formatting operations replaces the `%` string formatting operator. (However, the `%` operator is still supported; it will be deprecated in Python 3.1 and removed from the language at some later time.) Read [PEP 3101][] for the full scoop. - -Changes To Exceptions -=========== -- [x] [PEP 0352][]: All exceptions must be derived (directly or indirectly) from `BaseException`. This is the root of the exception hierarchy. This is not new as a recommendation, but the requirement to inherit from `BaseException` is new. (Python 2.6 still allowed classic classes to be raised, and placed no restriction on what you can catch.) As a consequence, string exceptions are finally truly and utterly dead. -- [x] Almost all exceptions should actually derive from `Exception`; `BaseException` should only be used as a base class for exceptions that should only be handled at the top level, such as `SystemExit` or `KeyboardInterrupt`. The recommended idiom for handling all exceptions except for this latter category is to use `except Exception`. -- [x] `StandardError` was removed (in 2.6 already). -- [x] Exceptions no longer behave as sequences. Use the `args` attribute instead. -- [x] [PEP 3109][]: Raising exceptions. You must now use `raise Exception(args)` instead of `raise Exception, args`. Additionally, you can no longer explicitly specify a traceback; instead, if you have to do this, you can assign directly to the `__traceback__` attribute (see below). -- [x] [PEP 3110][]: Catching exceptions. You must now use `except SomeException as variable` instead of `except SomeException, variable`. Moreover, the variable is explicitly deleted when the `except` block is left. -- [x] [PEP 3134][]: Exception chaining. There are two cases: implicit chaining and explicit chaining. Implicit chaining happens when an exception is raised in an `except` or `finally` handler block. This usually happens due to a bug in the handler block; we call this a secondary exception. In this case, the original exception (that was being handled) is saved as the `__context__` attribute of the secondary exception. Explicit chaining is invoked with this syntax: `raise SecondaryException() from primary_exception` (where `primary_exception` is any expression that produces an exception object, probably an exception that was previously caught). In this case, the primary exception is stored on the `__cause__` attribute of the secondary exception. The traceback printed when an unhandled exception occurs walks the chain of `__cause__` and `__context__` attributes and prints a separate traceback for each component of the chain, with the primary exception at the top. (Java users may recognize this behavior.) -- [x] [PEP 3134][]: Exception objects now store their traceback as the `__traceback__` attribute. This means that an exception object now contains all the information pertaining to an exception, and there are fewer reasons to use `sys.exc_info()` (though the latter is not removed). -- [x] A few exception messages are improved when Windows fails to load an extension module. For example, error code 193 is now `%1 is not a valid Win32 application`. Strings now deal with non-English locales. - -Operators And Special Methods -=============== -- [x] `!=` now returns the opposite of `==`, unless `==` returns `NotImplemented`. -- [x] The concept of "unbound methods" has been removed from the language. When referencing a method as a class attribute, you now get a plain function object. -- [x] `__getslice__()`, `__setslice__()` and `__delslice__()` were killed. The syntax `a[i:j]` now translates to `a.__getitem__(slice(i, j))` (or `__setitem__()` or `__delitem__()`, when used as an assignment or deletion target, respectively). -- [x] [PEP 3114][]: the standard `next()` method has been renamed to `__next__()`. -- [x] The `__oct__()` and `__hex__()` special methods are removed - `oct()` and `hex()` use `__index__()` now to convert the argument to an integer. -- [x] Removed support for `__members__` and `__methods__`. -- [x] The function attributes named `func_X` have been renamed to use the `__X__` form, freeing up these names in the function attribute namespace for user-defined attributes. To wit, `func_closure`, `func_code`, `func_defaults`, `func_dict`, `func_doc`, `func_globals`, `func_name` were renamed to `__closure__`, `__code__`, `__defaults__`, `__dict__`, `__doc__`, `__globals__`, `__name__`, respectively. -- [x] `__nonzero__()` is now `__bool__()`. - -Builtins -===== -- [x] [PEP 3135][]: New `super()`. You can now invoke `super()` without arguments and (assuming this is in a regular instance method defined inside a class statement) the right class and instance will automatically be chosen. With arguments, the behavior of `super()` is unchanged. -- [x] [PEP 3111][]: `raw_input()` was renamed to `input()`. That is, the new `input()` function reads a line from `sys.stdin` and returns it with the trailing newline stripped. It raises `EOFError` if the input is terminated prematurely. To get the old behavior of `input()`, use `eval(input())`. -- [x] A new builtin `next()` was added to call the `__next__()` method on an object. -- [x] Moved `intern()` to `sys.intern()` -- [x] Removed: `apply()`. Instead of `apply(f, args)` use `f(*args)`. -- [x] ~~Removed `callable()`. Instead of `callable(f)` you can use `hasattr(f, '__call__')`.~~ (Readded in Python 3.2) The `operator.isCallable()` function is also gone. -- [x] Removed `coerce()`. This function no longer serves a purpose now that classic classes are gone. -- [x] Removed `execfile()`. Instead of `execfile(fn)` use `exec(open(fn).read())`. -- [x] Removed `file`. Use `open()`. -- [x] Removed `reduce()`. Use `functools.reduce()` -- [x] Removed `reload()`. Use `imp.reload()`. -- [x] Removed `dict.has_key()` - use the `in` operator instead. - -[PEP 0237]: https://python.org/dev/peps/pep-0237 -[PEP 0238]: https://python.org/dev/peps/pep-0238 -[PEP 3138]: https://python.org/dev/peps/pep-3138 -[PEP 3120]: https://python.org/dev/peps/pep-3120 -[PEP 3131]: https://python.org/dev/peps/pep-3131 -[PEP 3107]: https://python.org/dev/peps/pep-3107 -[PEP 3102]: https://python.org/dev/peps/pep-3102 -[PEP 3104]: https://python.org/dev/peps/pep-3104 -[PEP 3132]: https://python.org/dev/peps/pep-3132 -[PEP 0274]: https://python.org/dev/peps/pep-0274 -[PEP 3109]: https://python.org/dev/peps/pep-3109 -[PEP 3134]: https://python.org/dev/peps/pep-3134 -[PEP 3110]: https://python.org/dev/peps/pep-3110 -[PEP 3115]: https://python.org/dev/peps/pep-3115 -[PEP 3113]: https://python.org/dev/peps/pep-3113 -[PEP 0328]: https://python.org/dev/peps/pep-0328 -[PEP 3101]: https://python.org/dev/peps/pep-3101 -[PEP 3101]: https://python.org/dev/peps/pep-3101 -[PEP 0352]: https://python.org/dev/peps/pep-0352 -[PEP 3109]: https://python.org/dev/peps/pep-3109 -[PEP 3110]: https://python.org/dev/peps/pep-3110 -[PEP 3134]: https://python.org/dev/peps/pep-3134 -[PEP 3134]: https://python.org/dev/peps/pep-3134 -[PEP 3114]: https://python.org/dev/peps/pep-3114 -[PEP 3135]: https://python.org/dev/peps/pep-3135 -[PEP 3111]: https://python.org/dev/peps/pep-3111 diff --git a/WhatsNewInPython31.md b/WhatsNewInPython31.md deleted file mode 100644 index 537900b8f..000000000 --- a/WhatsNewInPython31.md +++ /dev/null @@ -1,42 +0,0 @@ -# What's New In Python 3.1 - -https://docs.python.org/3/whatsnew/3.1.html - -PEPs -==== -- [x] [PEP 372][]: Ordered Dictionaries -- [x] [PEP 378][]: Format Specifier for Thousands Separator - -Other Language Changes -======================= -- [ ] Directories and zip archives containing a `__main__.py` file can now be executed directly by passing their name to the interpreter. The directory/zipfile is automatically inserted as the first entry in `sys.path`. -- [x] The `int()` type gained a `bit_length` method that returns the number of bits necessary to represent its argument in binary. -- [x] The fields in `format()` strings can now be automatically numbered. -- [x] The `string.maketrans()` function is deprecated and is replaced by new static methods, `bytes.maketrans()` and `bytearray.maketrans()`. This change solves the confusion around which types were supported by the string module. Now, `str`, `bytes`, and `bytearray` each have their own `maketrans` and `translate` methods with intermediate translation tables of the appropriate type. -- [x] The syntax of the `with` statement now allows multiple context managers in a single statement. -- [x] `round(x, n)` now returns an integer if `x` is an integer. Previously it returned a `float`. -- [ ] Python now uses David Gay's algorithm for finding the shortest floating point representation that doesn't change its value. - -New, Improved, and Deprecated Modules -============== -- [x] Added a `collections.Counter` class to support convenient counting of unique items in a sequence or iterable. -- [ ] Added a new module, `tkinter.ttk` for access to the Tk themed widget set. The basic idea of `ttk` is to separate, to the extent possible, the code implementing a widget's behavior from the code implementing its appearance. -- [ ] The `gzip.GzipFile` and `bz2.BZ2File` classes now support the context management protocol. -- [x] The `decimal` module now supports methods for creating a decimal object from a binary float. -- [x] The `itertools` module grew two new functions. The `itertools.combinations_with_replacement()` function is one of four for generating combinatorics including permutations and Cartesian products. The `itertools.compress()` function mimics its namesake from APL. Also, the existing `itertools.count()` function now has an optional step argument and can accept any type of counting sequence including `fractions.Fraction` and `decimal.Decimal`. -- [x] `collections.namedtuple()` now supports a keyword argument rename which lets invalid fieldnames be automatically converted to positional names in the form `_0`, `_1`, etc. This is useful when the field names are being created by an external source such as a CSV header, SQL field list, or user input. -- [x] The `re.sub()`, `re.subn()` and `re.split()` functions now accept a `flags` parameter. -- [ ] The `logging` module now implements a simple `logging.NullHandler` class for applications that are not using logging but are calling library code that does. Setting-up a null handler will suppress spurious warnings such as "No handlers could be found for logger foo". -- [ ] The `runpy` module which supports the `-m` command line switch now supports the execution of packages by looking for and executing a `__main__` submodule when a package name is supplied. -- [ ] The `pdb` module can now access and display source code loaded via `zipimport` (or any other conformant PEP 302 loader). -- [ ] `functools.partial` objects can now be pickled. -- [ ] Add `pydoc` help topics for symbols so that `help('@')` works as expected in the interactive environment. -- [ ] The `unittest` module now supports skipping individual tests or classes of tests. And it supports marking a test as an expected failure, a test that is known to be broken, but shouldn't be counted as a failure on a `TestResult`. Also, tests for exceptions have been built out to work with context managers using the `with` statement. In addition, several new assertion methods were added including `assertSetEqual()`, `assertDictEqual()`, `assertDictContainsSubset()`, `assertListEqual()`, `assertTupleEqual()`, `assertSequenceEqual()`, `assertRaisesRegexp()`, `assertIsNone()`, and `assertIsNotNone()`. -- [x] The `io` module has three new constants for the `seek()` method: `SEEK_SET`, `SEEK_CUR`, and `SEEK_END`. -- [x] `sys.version_info` tuple is now a named tuple. -- [ ] The `nntplib` and `imaplib` modules now support IPv6. -- [ ] The `pickle` module has been adapted for better interoperability with Python 2.x when used with protocol 2 or lower. The reorganization of the standard library changed the formal reference for many objects. For example, `__builtin__.set` in Python 2 is called `builtins.set` in Python 3. This change confounded efforts to share data between different versions of Python. But now when protocol 2 or lower is selected, the pickler will automatically use the old Python 2 names for both loading and dumping. This remapping is turned-on by default but can be disabled with the `fix_imports` option. An unfortunate but unavoidable side-effect of this change is that protocol 2 pickles produced by Python 3.1 won't be readable with Python 3.0. The latest pickle protocol, protocol 3, should be used when migrating data between Python 3.x implementations, as it doesn't attempt to remain compatible with Python 2.x. -- [ ] A new module, `importlib` was added. It provides a complete, portable, pure Python reference implementation of the `import` statement and its counterpart, the `__import__()` function. It represents a substantial step forward in documenting and defining the actions that take place during imports. - -[PEP 372]: https://python.org/dev/peps/pep-0372 -[PEP 378]: https://python.org/dev/peps/pep-0378 diff --git a/WhatsNewInPython32.md b/WhatsNewInPython32.md deleted file mode 100644 index a32d2d5a6..000000000 --- a/WhatsNewInPython32.md +++ /dev/null @@ -1,128 +0,0 @@ -# What's New In Python 3.2 - -https://docs.python.org/3/whatsnew/3.2.html - -PEPs -==== -- [ ] [PEP 384][]: Defining a Stable ABI -- [ ] [PEP 389][]: `Argparse` Command Line Parsing Module -- [ ] [PEP 391][]: Dictionary Based Configuration for Logging -- [ ] [PEP 3148][]: The `concurrent.futures` module -- [ ] [PEP 3147][]: PYC Repository Directories -- [ ] [PEP 3149][]: ABI Version Tagged `.so` Files -- [ ] [PEP 3333][]: Python Web Server Gateway Interface v1.0.1 - -Other Language Changes -============== -- [ ] String formatting for `format()` and `str.format()` gained new capabilities for the format character `#`. Previously, for integers in binary, octal, or hexadecimal, it caused the output to be prefixed with `'0b'`, `'0o'`, or `'0x'` respectively. Now it can also handle floats, complex, and `Decimal`, causing the output to always have a decimal point even when no digits follow it. -- [ ] There is also a new `str.format_map()` method that extends the capabilities of the existing `str.format()` method by accepting arbitrary mapping objects. This new method makes it possible to use string formatting with any of Python's many dictionary-like objects such as `defaultdict`, `Shelf`, `ConfigParser`, or `dbm`. It is also useful with custom `dict` subclasses that normalize keys before look-up or that supply a `__missing__()` method for unknown keys. -- [x] The interpreter can now be started with a quiet option, `-q`, to prevent the copyright and version information from being displayed in the interactive mode. The option can be introspected using the `sys.flags` attribute. -- [ ] The `hasattr()` function works by calling `getattr()` and detecting whether an exception is raised. This technique allows it to detect methods created dynamically by `__getattr__()` or `__getattribute__()` which would otherwise be absent from the class dictionary. Formerly, `hasattr` would catch any exception, possibly masking genuine errors. Now, `hasattr` has been tightened to only catch `AttributeError` and let other exceptions pass through. -- [x] The `str()` of a float or complex number is now the same as its `repr()`. Previously, the `str()` form was shorter but that just caused confusion and is no longer needed now that the shortest possible `repr()` is displayed by default. -- [x] `memoryview` objects now have a `release()` method and they also now support the context management protocol. This allows timely release of any resources that were acquired when requesting a buffer from the original object. -- [ ] Previously it was illegal to delete a name from the local namespace if it occurs as a free variable in a nested block. This is now allowed. -- [ ] The internal `structsequence` tool now creates subclasses of tuple. This means that C structures like those returned by `os.stat()`, `time.gmtime()`, and `sys.version_info` now work like a named tuple and now work with functions and methods that expect a tuple as an argument. This is a big step forward in making the C structures as flexible as their pure Python counterparts. -- [ ] Warnings are now easier to control using the `PYTHONWARNINGS` environment variable as an alternative to using `-W` at the command line. -- [ ] A new warning category, `ResourceWarning`, has been added. It is emitted when potential issues with resource consumption or cleanup are detected. It is silenced by default in normal release builds but can be enabled through the means provided by the `warnings` module, or on the command line. A `ResourceWarning` is issued at interpreter shutdown if the `gc.garbage` list isn't empty, and if `gc.DEBUG_UNCOLLECTABLE` is set, all uncollectable objects are printed. This is meant to make the programmer aware that their code contains object finalization issues. A `ResourceWarning` is also issued when a file object is destroyed without having been explicitly closed. While the deallocator for such object ensures it closes the underlying operating system resource (usually, a file descriptor), the delay in deallocating the object could produce various issues, especially under Windows. Here is an example of enabling the warning from the command line. -- [ ] `range` objects now support `index` and `count` methods. This is part of an effort to make more objects fully implement the `collections.Sequence` abstract base class. As a result, the language will have a more uniform API. In addition, `range` objects now support slicing and negative indices, even with values larger than `sys.maxsize`. This makes `range` more interoperable with lists. -- [x] The `callable()` builtin function from Py2.x was resurrected. It provides a concise, readable alternative to using an abstract base class in an expression like `isinstance(x, collections.Callable)`. -- [ ] Python's import mechanism can now load modules installed in directories with non-ASCII characters in the path name. This solved an aggravating problem with home directories for users with non-ASCII characters in their usernames. - -New, Improved, and Deprecated Modules -============== -- [ ] `email` - - [ ] New functions `message_from_bytes()` and `message_from_binary_file()`, and new classes `BytesFeedParser` and `BytesParser` allow binary message data to be parsed into model objects. - - [ ] Given bytes input to the model, `get_payload()` will by default decode a message body that has a `Content-Transfer-Encoding` of 8bit using the charset specified in the MIME headers and return the resulting string. - - [ ] Given bytes input to the model, Generator will convert message bodies that have a `Content-Transfer-Encoding` of 8bit to instead have a 7bit `Content-Transfer-Encoding`. Headers with unencoded non-ASCII bytes are deemed to be RFC 2047-encoded using the unknown-8bit character set. - - [ ] A new class `BytesGenerator` produces bytes as output, preserving any unchanged non-ASCII data that was present in the input used to build the model, including message bodies with a `Content-Transfer-Encoding` of 8bit. - - [ ] The `smtplib` SMTP class now accepts a byte string for the `msg` argument to the `sendmail()` method, and a new method, `send_message()` accepts a `Message` object and can optionally obtain the `from_addr` and `to_addrs` addresses directly from the object. -- [ ] The `xml.etree.ElementTree` package and its `xml.etree.cElementTree` counterpart have been updated to version 1.3. -- [x] `functools` - + [x] The `functools` module includes a new decorator for caching function calls. `functools.lru_cache()` can save repeated queries to an external resource whenever the results are expected to be the same. - + [x] The `functools.wraps()` decorator now adds a `__wrapped__` attribute pointing to the original callable function. This allows wrapped functions to be introspected. It also copies `__annotations__` if defined. And now it also gracefully skips over missing attributes such as `__doc__` which might not be defined for the wrapped callable. - + [x] To help write classes with rich comparison methods, a new decorator `functools.total_ordering()` will use existing equality and inequality methods to fill in the remaining methods. - + [x] To aid in porting programs from Python 2, the `functools.cmp_to_key()` function converts an old-style comparison function to modern key function. -- [x] The `itertools` module has a `new accumulate()` function modeled on APL's scan operator and Numpy's `accumulate` function. -- [ ] `collections` - + [ ] The `collections.Counter` class now has two forms of in-place subtraction, the existing `-=` operator for saturating subtraction and the new `subtract()` method for regular subtraction. The former is suitable for multisets which only have positive counts, and the latter is more suitable for use cases that allow negative counts. - + [x] The `collections.OrderedDict` class has a new method `move_to_end()` which takes an existing key and moves it to either the first or last position in the ordered sequence. The default is to move an item to the last position. This is equivalent of renewing an entry with `od[k] = od.pop(k)`. A fast move-to-end operation is useful for resequencing entries. For example, an ordered dictionary can be used to track order of access by aging entries from the oldest to the most recently accessed. - + [x] The `collections.deque` class grew two new methods `count()` and `reverse()` that make them more substitutable for `list` objects. -- [ ] `threading` -- [ ] `datetime` and `time` - + [x] The `datetime` module has a new type `timezone` that implements the `tzinfo` interface by returning a fixed UTC offset and timezone name. This makes it easier to create timezone-aware `datetime` objects. - + [x] Also, `timedelta` objects can now be multiplied by `float` and divided by `float` and `int` objects. And `timedelta` objects can now divide one another. - + [ ] The `datetime.date.strftime()` method is no longer restricted to years after 1900. The new supported year range is from 1000 to 9999 inclusive. - + [ ] Whenever a two-digit year is used in a time tuple, the interpretation has been governed by `time.accept2dyear`. The default is `True` which means that for a two-digit year, the century is guessed according to the POSIX rules governing the `%y` `strptime` format. Starting with Py3.2, use of the century guessing heuristic will emit a `DeprecationWarning`. Instead, it is recommended that `time.accept2dyear` be set to `False` so that large date ranges can be used without guesswork. Several functions now have significantly expanded date ranges. When `time.accept2dyear` is false, the `time.asctime()` function will accept any year that fits in a C `int`, while the `time.mktime()` and `time.strftime()` functions will accept the full range supported by the corresponding operating system functions. -- [x] math - - [x] The `isfinite()` function provides a reliable and fast way to detect special values. It returns `True` for regular numbers and `False` for `Nan` or `Infinity`. - - [x] The `expm1()` function computes `e**x-1` for small values of `x` without incurring the loss of precision that usually accompanies the subtraction of nearly equal quantities. - - [x] The `erf()` function computes a probability integral or Gaussian error function. The complementary error function, `erfc()`, is `1 - erf(x)`: - - [x] The `gamma()` function is a continuous extension of the factorial function. See https://en.wikipedia.org/wiki/Gamma_function for details. Because the function is related to factorials, it grows large even for small values of x, so there is also a `lgamma()` function for computing the natural logarithm of the gamma function. -- [ ] `abc` -- [ ] `io` -- [ ] `reprlib` -- [ ] `logging` -- [ ] `csv` -- [ ] `contextlib` -- [ ] `decimal and fractions` -- [ ] `ftp` -- [ ] `popen` -- [ ] `select` -- [ ] `gzip and zipfile` -- [ ] `tarfile` -- [ ] `hashlib` -- [ ] `ast` -- [ ] `os` -- [ ] `shutil` -- [ ] `sqlite3` -- [ ] `html` -- [ ] `socket` -- [ ] `ssl` -- [ ] `nntp` -- [ ] `certificates` -- [ ] `imaplib` -- [ ] `http.client` -- [ ] `unittest` -- [ ] `random` -- [ ] `poplib` -- [ ] `asyncore` -- [ ] `tempfile` -- [ ] `inspect` -- [ ] `pydoc` -- [ ] `dis` -- [ ] `dbm` -- [ ] `ctypes` - + [ ] A new type, `ctypes.c_ssize_t` represents the C `ssize_t` datatype. -- [ ] `site` -- [ ] `sysconfig` -- [ ] `pdb` -- [ ] `configparser` -- [ ] `urllib.parse` -- [ ] `mailbox` -- [ ] `turtledemo` - -Porting to Python 3.2 -============ -- [x] The `configparser` module has a number of clean-ups. -- [x] The `nntplib` module was reworked extensively, meaning that its APIs are often incompatible with the 3.1 APIs. -- [ ] `bytearray` objects can no longer be used as filenames; instead, they should be converted to `bytes`. -- [x] The `array.tostring()` and `array.fromstring()` have been renamed to `array.tobytes()` and `array.frombytes()` for clarity. The old names have been deprecated. (See issue 8990.) -- [x] The `sys.setfilesystemencoding()` function was removed because it had a flawed design. -- [ ] The `random.seed()` function and method now salt string seeds with an sha512 hash function. To access the previous version of seed in order to reproduce Python 3.1 sequences, set the version argument to 1, `random.seed(s, version=1)`. -- [x] The previously deprecated `string.maketrans()` function has been removed in favor of the static methods `bytes.maketrans()` and `bytearray.maketrans()`. This change solves the confusion around which types were supported by the string module. Now, `str`, `bytes`, and `bytearray` each have their own `maketrans` and `translate` methods with intermediate translation tables of the appropriate type. -- [x] The previously deprecated `contextlib.nested()` function has been removed in favor of a plain `with` statement which can accept multiple context managers. The latter technique is faster (because it is built-in), and it does a better job finalizing multiple context managers when one of them raises an exception. -- [x] `struct.pack()` now only allows bytes for the s string pack code. Formerly, it would accept text arguments and implicitly encode them to bytes using UTF-8. This was problematic because it made assumptions about the correct encoding and because a variable-length encoding can fail when writing to fixed length segment of a structure. Code such as `struct.pack('<6sHHBBB', 'GIF87a', x, y)` should be rewritten with to use bytes instead of text, `struct.pack('<6sHHBBB', b'GIF87a', x, y)`. -- [ ] The `xml.etree.ElementTree` class now raises an `xml.etree.ElementTree.ParseError` when a parse fails. Previously it raised an `xml.parsers.expat.ExpatError`. -- [ ] The new, longer `str()` value on floats may break `doctest`s which rely on the old output format. -- [ ] In `subprocess.Popen`, the default value for `close_fds` is now `True` under Unix; under Windows, it is `True` if the three standard streams are set to `None`, `False` otherwise. Previously, `close_fds` was always `False` by default, which produced difficult to solve bugs or race conditions when open file descriptors would leak into the child process. -- [ ] Support for legacy HTTP 0.9 has been removed from `urllib.request` and `http.client`. Such support is still present on the server side (in `http.server`). -- [ ] SSL sockets in timeout mode now raise `socket.timeout` when a timeout occurs, rather than a generic `SSLError`. -- [ ] Due to security risks, `asyncore.handle_accept()` has been deprecated, and a new function, `asyncore.handle_accepted()`, was added to replace it. - -[PEP 384]: https://python.org/dev/peps/pep-0384 -[PEP 389]: https://python.org/dev/peps/pep-0389 -[PEP 391]: https://python.org/dev/peps/pep-0391 -[PEP 3148]: https://python.org/dev/peps/pep-3148 -[PEP 3147]: https://python.org/dev/peps/pep-3147 -[PEP 3149]: https://python.org/dev/peps/pep-3149 -[PEP 3333]: https://python.org/dev/peps/pep-3333 diff --git a/WhatsNewInPython33.md b/WhatsNewInPython33.md deleted file mode 100644 index 08aee7fe7..000000000 --- a/WhatsNewInPython33.md +++ /dev/null @@ -1,141 +0,0 @@ -# What's New In Python 3.3 - -https://docs.python.org/3/whatsnew/3.3.html - -PEPs -==== -- [ ] [PEP 405][]: Virtual Environments -- [ ] [PEP 420][]: Implicit Namespace Packages -- [ ] [PEP 3118][]: New `memoryview` implementation and buffer protocol documentation -- [ ] [PEP 393][]: Flexible String Representation -- [ ] [PEP 397][]: Python Launcher for Windows -- [ ] [PEP 3151][]: Reworking the OS and IO exception hierarchy -- [ ] [PEP 380][]: Syntax for Delegating to a Subgenerator -- [ ] [PEP 409][]: Suppressing exception context -- [x] [PEP 414][]: Explicit Unicode literals -- [ ] [PEP 3155][]: Qualified name for classes and functions -- [ ] [PEP 412][]: Key-Sharing Dictionary -- [ ] [PEP 362][]: Function Signature Object -- [x] [PEP 421][]: Adding `sys.implementation` - -Using `importlib` as the Implementation of Import -=============================================== -- [ ] See https://docs.python.org/3/whatsnew/3.3.html#using-importlib-as-the-implementation-of-import - -Other Language Changes -====================== -- [ ] Added support for Unicode name aliases and named sequences. Both `unicodedata.lookup()` and `'\N{...}'` now resolve name aliases, and `unicodedata.lookup()` resolves named sequences too. -- [ ] Unicode database updated to UCD version 6.1.0 -- [ ] Equality comparisons on `range()` objects now return a result reflecting the equality of the underlying sequences generated by those range objects. -- [x] The `count()`, `find()`, `rfind()`, `index()` and `rindex()` methods of `bytes` and `bytearray` objects now accept an integer between 0 and 255 as their first argument. -- [x] The `rjust()`, `ljust()`, and `center()` methods of `bytes` and `bytearray` now accept a `bytearray` for the `fill` argument. -- [x] New methods have been added to `list` and `bytearray`: `copy()` and `clear()`. Consequently, `MutableSequence` now also defines a `clear()` method -- [x] Raw `bytes` literals can now be written `rb"..."` as well as `br"..."`. -- [ ] `dict.setdefault()` now does only one lookup for the given key, making it atomic when used with built-in types. -- [ ] The error messages produced when a function call does not match the function signature have been significantly improved. - -Builtin functions and types -=========================== -- [ ] `open()` gets a new `opener` parameter: the underlying file descriptor for the file object is then obtained by calling `opener` with `(file, flags)`. It can be used to use custom flags like `os.O_CLOEXEC` for example. The `'x'` mode was added: open for exclusive creation, failing if the file already exists. -- [ ] `print()`: added the `flush` keyword argument. If the `flush` keyword argument is true, the stream is forcibly flushed. -- [ ] `hash()`: hash randomization is enabled by default, see `object.__hash__()` and `PYTHONHASHSEED`. -- [ ] The `str` type gets a new `casefold()` method: return a casefolded copy of the string, casefolded strings may be used for caseless matching. For example, `''.casefold()` returns `'ss'`. - -New Modules -=========== -- [ ] `faulthandler` -- [x] `ipaddress` -- [ ] `lzma` - -Improved Modules -================ -- [ ] `abc` -- [ ] `array` -- [ ] `base64` -- [ ] `binascii` -- [ ] `bz2` -- [ ] `codecs` -- [ ] `collections` -- [ ] `contextlib` -- [ ] `crypt` -- [ ] `curses` -- [ ] `datetime` -- [ ] `decimal` -- [ ] `email` -- [ ] `ftplib` -- [ ] `functools` -- [ ] `gc` -- [ ] `hmac` -- [ ] `http` -- [ ] `html` -- [ ] `imaplib` -- [ ] `inspect` -- [ ] `io` -- [ ] `itertools` -- [ ] `logging` -- [ ] `math` -- [ ] `mmap` -- [ ] `multiprocessing` -- [ ] `nntplib` -- [ ] `os` -- [ ] `pdb` -- [ ] `pickle` -- [ ] `pydoc` -- [ ] `re` -- [ ] `sched` -- [ ] `select` -- [ ] `shlex` -- [ ] `shutil` -- [ ] `signal` -- [ ] `smtpd` -- [ ] `smtplib` -- [ ] `socket` -- [ ] `socketserver` -- [ ] `sqlite3` -- [ ] `ssl` -- [ ] `stat` -- [ ] `struct` -- [ ] `subprocess` -- [ ] `sys` -- [ ] `tarfile` -- [ ] `tempfile` -- [ ] `textwrap` -- [ ] `threading` -- [ ] `time` -- [ ] `types` -- [ ] `unittest` -- [ ] `urllib` -- [ ] `webbrowser` -- [ ] `xml.etree.ElementTree` -- [ ] `zlib` - -Deprecated Python modules, functions and methods -============== -- [ ] Passing a non-empty string to `object.__format__()` is deprecated, and will produce a `TypeError` in Python 3.4 -- [ ] The unicode_internal codec has been deprecated because of the [PEP 393][], use UTF-8, UTF-16 (`utf-16-le` or `utf-16-be`), or UTF-32 (`utf-32-le` or `utf-32-be`) -- [ ] `ftplib.FTP.nlst()` and `ftplib.FTP.dir()`: use `ftplib.FTP.mlsd()` -- [ ] `platform.popen()`: use the `subprocess` module. Check especially the "Replacing Older Functions with the `subprocess` Module" section (issue 11377). -- [ ] The Windows `bytes` API has been deprecated in the `os` module. Use Unicode filenames, instead of `bytes` filenames, to not depend on the ANSI code page anymore and to support any filename. -- [x] The `xml.etree.cElementTree` module is deprecated. The accelerator is used automatically whenever available. -- [x] The behaviour of `time.clock()` depends on the platform: use the new `time.perf_counter()` or `time.process_time()` function instead, depending on your requirements, to have a well defined behaviour. -- [x] ~~The `os.stat_float_times()` function is deprecated.~~ (Never implemented, but removed in Python 3.7) -- `abc` module: - + [ ] `abc.abstractproperty` has been deprecated, use `property` with `abc.abstractmethod()` instead. - + [ ] `abc.abstractclassmethod` has been deprecated, use `classmethod` with `abc.abstractmethod()` instead. - + [ ] `abc.abstractstaticmethod` has been deprecated, use `staticmethod` with `abc.abstractmethod()` instead. -- [ ] `importlib.abc.SourceLoader.path_mtime()` is now deprecated in favour of `importlib.abc.SourceLoader.path_stats()` as bytecode files now store both the modification time and size of the source file the bytecode file was compiled from. - -[PEP 405]: http://www.python.org/dev/peps/pep-0405 -[PEP 420]: http://www.python.org/dev/peps/pep-0420 -[PEP 3118]: http://www.python.org/dev/peps/pep-3118 -[PEP 393]: http://www.python.org/dev/peps/pep-0393 -[PEP 397]: http://www.python.org/dev/peps/pep-0397 -[PEP 3151]: http://www.python.org/dev/peps/pep-3151 -[PEP 380]: http://www.python.org/dev/peps/pep-0380 -[PEP 409]: http://www.python.org/dev/peps/pep-0409 -[PEP 414]: http://www.python.org/dev/peps/pep-0414 -[PEP 3155]: http://www.python.org/dev/peps/pep-3155 -[PEP 412]: http://www.python.org/dev/peps/pep-0412 -[PEP 362]: http://www.python.org/dev/peps/pep-0362 -[PEP 421]: http://www.python.org/dev/peps/pep-0421 -[PEP 393]: http://www.python.org/dev/peps/pep-0393 diff --git a/WhatsNewInPython34.md b/WhatsNewInPython34.md deleted file mode 100644 index 241983e5a..000000000 --- a/WhatsNewInPython34.md +++ /dev/null @@ -1,143 +0,0 @@ -# What's New In Python 3.4 - -https://docs.python.org/3/whatsnew/3.4.html - -PEPs -==== -- [ ] [PEP 453][]: Explicit Bootstrapping of PIP in Python Installations -- [ ] [PEP 446][]: Newly created file descriptors are non-inheritable -- [ ] [PEP 451][]: A `ModuleSpec` Type for the Import System - -Improvements to Codec Handling -============================== -- [ ] See https://docs.python.org/3/whatsnew/3.4.html#improvements-to-codec-handling - -Other Language Changes -====================== -- [ ] Unicode database updated to UCD version 6.3. -- [x] `min()` and `max()` now accept a default keyword-only argument that can be used to specify the value they return if the iterable they are evaluating has no elements. -- [ ] Module objects are now `weakref`’able. -- [ ] Module `__file__` attributes (and related values) should now always contain absolute paths by default, with the sole exception of `__main__.__file__` when a script has been executed directly using a relative path. -- [ ] All the UTF-* codecs (except UTF-7) now reject surrogates during both encoding and decoding unless the surrogatepass error handler is used, with the exception of the UTF-16 decoder and the UTF-16 encoder -- [ ] New German EBCDIC codec `cp273`. -- [ ] New Ukrainian codec `cp1125`. -- [ ] `bytes.join()` and `bytearray.join()` now accept arbitrary buffer objects as arguments. -- [ ] The `int` constructor now accepts any object that has an `__index__` method for its base argument. -- [ ] Frame objects now have a `clear()` method that clears all references to local variables from the frame. -- [ ] `memoryview` is now registered as a `Sequence`, and supports the `reversed()` builtin. -- [ ] Signatures reported by `help()` have been modified and improved in several cases as a result of the introduction of Argument Clinic and other changes to the `inspect` and `pydoc` modules. -- [ ] `__length_hint__()` is now part of the formal language specification - -New Modules -=========== -- [ ] `asyncio` -- [ ] `ensurepip` -- [ ] `enum` -- [ ] `pathlib` -- [ ] `selectors` -- [ ] `statistics` -- [ ] `tracemalloc` - -Improved Modules -================ -- [ ] `abc` -- [ ] `aifc` -- [ ] `argparse` -- [ ] `audioop` -- [ ] `base64` -- [ ] `collections` -- [ ] `colorsys` -- [ ] `contextlib` -- [ ] `dbm` -- [ ] `dis` -- [ ] `doctest` -- [ ] `email` -- [ ] `filecmp` -- [ ] `functools` -- [ ] `gc` -- [ ] `glob` -- [ ] `hashlib` -- [ ] `hmac` -- [ ] `html` -- [ ] `http` -- [ ] `idlelib-and-idle` -- [ ] `importlib` -- [ ] `inspect` -- [ ] `ipaddress` -- [ ] `logging` -- [ ] `marshal` -- [ ] `mmap` -- [ ] `multiprocessing` -- [ ] `operator` -- [ ] `os` -- [ ] `pdb` -- [ ] `pickle` -- [ ] `plistlib` -- [ ] `poplib` -- [ ] `pprint` -- [ ] `pty` -- [ ] `pydoc` -- [ ] `re` -- [ ] `resource` -- [ ] `select` -- [ ] `shelve` -- [ ] `shutil` -- [ ] `smtpd` -- [ ] `smtplib` -- [ ] `socket` -- [ ] `sqlite3` -- [ ] `ssl` -- [ ] `stat` -- [ ] `struct` -- [ ] `subprocess` -- [ ] `sunau` -- [ ] `sys` -- [ ] `tarfile` -- [ ] `textwrap` -- [ ] `threading` -- [ ] `traceback` -- [ ] `types` -- [ ] `urllib` -- [ ] `unittest` -- [ ] `venv` -- [ ] `wave` -- [ ] `weakref` -- [ ] `xml.etree` -- [ ] `zipfile` - - -Deprecations in the Python API -============================== -- [ ] As mentioned in PEP 451: A ModuleSpec Type for the Import System, a number of importlib methods and functions are deprecated: importlib.find_loader() is replaced by importlib.util.find_spec(); importlib.machinery.PathFinder.find_module() is replaced by importlib.machinery.PathFinder.find_spec(); importlib.abc.MetaPathFinder.find_module() is replaced by importlib.abc.MetaPathFinder.find_spec(); importlib.abc.PathEntryFinder.find_loader() and find_module() are replaced by importlib.abc.PathEntryFinder.find_spec(); all of the xxxLoader ABC load_module methods (importlib.abc.Loader.load_module(), importlib.abc.InspectLoader.load_module(), importlib.abc.FileLoader.load_module(), importlib.abc.SourceLoader.load_module()) should no longer be implemented, instead loaders should implement an exec_module method (importlib.abc.Loader.exec_module(), importlib.abc.InspectLoader.exec_module() importlib.abc.SourceLoader.exec_module()) and let the import system take care of the rest; and importlib.abc.Loader.module_repr(), importlib.util.module_for_loader(), importlib.util.set_loader(), and importlib.util.set_package() are no longer needed because their functions are now handled automatically by the import system. -- [ ] The imp module is pending deprecation. To keep compatibility with Python 2/3 code bases, the module's removal is currently not scheduled. -- [ ] The formatter module is pending deprecation and is slated for removal in Python 3.6. -- [ ] MD5 as the default digestmod for the hmac.new() function is deprecated. Python 3.6 will require an explicit digest name or constructor as digestmod argument. -- [ ] The internal Netrc class in the ftplib module has been documented as deprecated in its docstring for quite some time. It now emits a DeprecationWarning and will be removed completely in Python 3.5. -- [ ] The undocumented endtime argument to subprocess.Popen.wait() should not have been exposed and is hopefully not in use; it is deprecated and will mostly likely be removed in Python 3.5. -- [ ] The strict argument of HTMLParser is deprecated. -- [ ] The plistlib readPlist(), writePlist(), readPlistFromBytes(), and writePlistToBytes() functions are deprecated in favor of the corresponding new functions load(), dump(), loads(), and dumps(). Data() is deprecated in favor of just using the bytes constructor. -- [ ] The sysconfig key SO is deprecated, it has been replaced by EXT_SUFFIX. -- [ ] The U mode accepted by various open functions is deprecated. In Python3 it does not do anything useful, and should be replaced by appropriate uses of io.TextIOWrapper (if needed) and its newline argument. -- [ ] The parser argument of xml.etree.ElementTree.iterparse() has been deprecated, as has the html argument of XMLParser(). To prepare for the removal of the latter, all arguments to XMLParser should be passed by keyword. - -Deprecated Features -=================== -- [ ] Running IDLE with the -n flag (no subprocess) is deprecated. However, the feature will not be removed until bpo-18823 is resolved. -- [ ] The site module adding a “site-python” directory to sys.path, if it exists, is deprecated (bpo-19375). - -API and Feature Removals -======================== -- [ ] The unmaintained Misc/TextMate and Misc/vim directories have been removed (see the devguide for suggestions on what to use instead). -- [ ] The SO makefile macro is removed (it was replaced by the SHLIB_SUFFIX and EXT_SUFFIX macros) (bpo-16754). -- [ ] The `PyThreadState.tick_counter` field has been removed; its value has been meaningless since Python 3.2, when the “new GIL” was introduced (bpo-19199). -- [ ] `PyLoader` and `PyPycLoader` have been removed from `importlib`. (Contributed by Taras Lyapun in bpo-15641.) -- [ ] The `strict` argument to `HTTPConnection` and `HTTPSConnection` has been removed. HTTP 0.9-style “Simple Responses” are no longer supported. -- [ ] The deprecated `urllib.request.Request` getter and setter methods `add_data`, `has_data`, `get_data`, `get_type`, `get_host`, `get_selector`, `set_proxy`, `get_origin_req_host`, and `is_unverifiable` have been removed (use direct attribute access instead). -- [ ] Support for loading the deprecated `TYPE_INT64` has been removed from marshal. (Contributed by Dan Riti in bpo-15480.) -- [ ] `inspect.Signature`: positional-only parameters are now required to have a valid name. -- [ ] `object.__format__()` no longer accepts non-empty format strings, it now raises a `TypeError` instead. Using a non-empty string has been deprecated since Python 3.2. This change has been made to prevent a situation where previously working (but incorrect) code would start failing if an object gained a `__format__` method, which means that your code may now raise a TypeError if you are using an 's' format code with objects that do not have a `__format__` method that handles it. See bpo-7994 for background. -- [ ] `difflib.SequenceMatcher.isbjunk()` and `difflib.SequenceMatcher.isbpopular()` were deprecated in 3.2, and have now been removed: use `x in sm.bjunk` and `x in sm.bpopular`, where `sm` is a `SequenceMatcher` object (bpo-13248). - -[PEP 453]: https://www.python.org/dev/peps/pep-0453 -[PEP 446]: https://www.python.org/dev/peps/pep-0446 -[PEP 451]: https://www.python.org/dev/peps/pep-0451 diff --git a/WhatsNewInPython35.md b/WhatsNewInPython35.md deleted file mode 100644 index f62f50776..000000000 --- a/WhatsNewInPython35.md +++ /dev/null @@ -1,154 +0,0 @@ -# What's New In Python 3.5 - -https://docs.python.org/3/whatsnew/3.5.html - -New Features -============ -- [ ] [PEP 492][]: Coroutines with async and await syntax -- [x] [PEP 465][]: A dedicated infix operator for matrix multiplication -- [x] [PEP 448][]: Additional Unpacking Generalizations -- [ ] [PEP 461][]: percent formatting support for bytes and bytearray -- [ ] [PEP 484][]: Type Hints -- [ ] [PEP 471][]: os.scandir() function – a better and faster directory iterator -- [ ] [PEP 475][]: Retry system calls failing with EINTR -- [x] [PEP 479][]: Change StopIteration handling inside generators -- [ ] [PEP 485][]: A function for testing approximate equality -- [ ] [PEP 486][]: Make the Python Launcher aware of virtual environments -- [ ] [PEP 488][]: Elimination of PYO files -- [ ] [PEP 489][]: Multi-phase extension module initialization - -Other Language Changes -====================== -- [ ] Added the `"namereplace"` error handlers. The `"backslashreplace"` error handlers now work with decoding and translating. -- [ ] The `-b` option now affects comparisons of `bytes` with `int`. -- [ ] New Kazakh `kz1048` and Tajik `koi8_t` codecs. -- [ ] Property docstrings are now writable. This is especially useful for `collections.namedtuple()` docstrings. -- [ ] Circular imports involving relative imports are now supported. - -New Modules -=========== -- [ ] `typing` -- [ ] `zipapp` - -Improved Modules -================ -- [ ] `argparse` -- [ ] `asyncio` -- [ ] `bz2` -- [ ] `cgi` -- [ ] `cmath` -- [ ] `code` -- [ ] `collections` -- [ ] `collections.abc` -- [ ] `compileall` -- [ ] `concurrent.futures` -- [ ] `configparser` -- [ ] `contextlib` -- [ ] `csv` -- [ ] `curses` -- [ ] `dbm` -- [ ] `difflib` -- [ ] `distutils` -- [ ] `doctest` -- [ ] `email` -- [ ] `enum` -- [ ] `faulthandler` -- [ ] `functools` -- [ ] `glob` -- [ ] `gzip` -- [ ] `heapq` -- [ ] `http` -- [ ] `http.client` -- [ ] `idlelib and IDLE` -- [ ] `imaplib` -- [ ] `imghdr` -- [ ] `importlib` -- [ ] `inspect` -- [ ] `io` -- [ ] `ipaddress` -- [ ] `json` -- [ ] `linecache` -- [ ] `locale` -- [ ] `logging` -- [ ] `lzma` -- [ ] `math` -- [ ] `multiprocessing` -- [ ] `operator` -- [ ] `os` -- [ ] `pathlib` -- [ ] `pickle` -- [ ] `poplib` -- [ ] `re` -- [ ] `readline` -- [ ] `selectors` -- [ ] `shutil` -- [ ] `signal` -- [ ] `smtpd` -- [ ] `smtplib` -- [ ] `sndhdr` -- [ ] `socket` -- [ ] `ssl` -- [ ] `sqlite3` -- [ ] `subprocess` -- [ ] `sys` -- [ ] `sysconfig` -- [ ] `tarfile` -- [ ] `threading` -- [ ] `time` -- [ ] `timeit` -- [ ] `tkinter` -- [ ] `traceback` -- [ ] `types` -- [ ] `unicodedata` -- [ ] `unittest` -- [ ] `unittest.mock` -- [ ] `urllib` -- [ ] `wsgiref` -- [ ] `xmlrpc` -- [ ] `xml.sax` -- [ ] `zipfile` - -Other module-level changes -========================== -- [ ] Many functions in the `mmap`, `ossaudiodev`, `socket`, `ssl`, and `codecs` modules now accept writable bytes-like objects. - -Deprecated -========== -- [ ] New Keywords: `async` and `await` are not recommended to be used as variable, class, function or module names. Introduced by PEP 492 in Python 3.5, they will become proper keywords in Python 3.7. -- [ ] Deprecated Python Behavior: Raising the `StopIteration` exception inside a generator will now generate a silent `PendingDeprecationWarning`, which will become a non-silent deprecation warning in Python 3.6 and will trigger a `RuntimeError` in Python 3.7. See PEP 479: Change StopIteration handling inside generators for details. - -Deprecated Python modules, functions and methods -================================================ -- [ ] The `formatter` module has now graduated to full deprecation and is still slated for removal in Python 3.6. -- [ ] The `asyncio.async()` function is deprecated in favor of `ensure_future()`. -- [ ] The `smtpd` module has in the past always decoded the DATA portion of email messages using the `utf-8` codec. This can now be controlled by the new _decode__data_ keyword to `SMTPServer`. The default value is `True`, but this default is deprecated. Specify the _decode__data_ keyword with an appropriate value to avoid the deprecation warning. -- [ ] Directly assigning values to the `key`, `value` and `coded_value` of `http.cookies.Morsel` objects is deprecated. Use the `set()` method instead. In addition, the undocumented LegalChars parameter of `set()` is deprecated, and is now ignored. -- [ ] Passing a format string as keyword argument _format__string_ to the `format()` method of the `string.Formatter` class has been deprecated. -- [ ] The `platform.dist()` and `platform.linux_distribution()` functions are now deprecated. Linux distributions use too many different ways of describing themselves, so the functionality is left to a package. -- [ ] The previously undocumented `from_function` and `from_builtin methods` of inspect.Signature are deprecated. Use the new `Signature.from_callable()` method instead. -- [ ] The `inspect.getargspec()` function is deprecated and scheduled to be removed in Python 3.6. -- [ ] The inspect `getfullargspec()`, `getcallargs()`, and `formatargspec()` functions are deprecated in favor of the `inspect.signature()` API. -- [ ] `getargvalues()` and `formatargvalues()` functions were inadvertently marked as deprecated with the release of Python 3.5.0. -- [ ] Use of `re.LOCALE` flag with str patterns or `re.ASCII` is now deprecated. -- [ ] Use of unrecognized special sequences consisting of `'\'` and an ASCII letter in regular expression patterns and replacement patterns now raises a deprecation warning and will be forbidden in Python 3.6. -- [ ] The undocumented and unofficial _use__load__tests_ default argument of the `unittest.TestLoader.loadTestsFromModule()` method now is deprecated and ignored. - -Removed -======= -- [ ] The `__version__` attribute has been dropped from the email package. The email code hasn’t been shipped separately from the stdlib for a long time, and the `__version__` string was not updated in the last few releases. -- [ ] The internal `Netrc` class in the ftplib module was deprecated in 3.4, and has now been removed. -- [ ] The concept of .pyo files has been removed. -- [ ] The `JoinableQueue` class in the provisional `asyncio` module was deprecated in 3.4.4 and is now removed. - -[PEP 492]: https://www.python.org/dev/peps/pep-0492 -[PEP 465]: https://www.python.org/dev/peps/pep-0465 -[PEP 448]: https://www.python.org/dev/peps/pep-0448 -[PEP 461]: https://www.python.org/dev/peps/pep-0461 -[PEP 484]: https://www.python.org/dev/peps/pep-0484 -[PEP 471]: https://www.python.org/dev/peps/pep-0471 -[PEP 475]: https://www.python.org/dev/peps/pep-0475 -[PEP 479]: https://www.python.org/dev/peps/pep-0479 -[PEP 485]: https://www.python.org/dev/peps/pep-0485 -[PEP 486]: https://www.python.org/dev/peps/pep-0486 -[PEP 488]: https://www.python.org/dev/peps/pep-0488 -[PEP 489]: https://www.python.org/dev/peps/pep-0489 diff --git a/WhatsNewInPython36.md b/WhatsNewInPython36.md deleted file mode 100644 index 34725b0e7..000000000 --- a/WhatsNewInPython36.md +++ /dev/null @@ -1,159 +0,0 @@ -# What's New In Python 3.6 - -https://docs.python.org/3/whatsnew/3.6.html - -New Features -============ -- [x] [PEP 498][]: Formatted string literals -- [ ] [PEP 526][]: Syntax for variable annotations -- [ ] [PEP 515][]: Underscores in Numeric Literals -- [ ] [PEP 525][]: Asynchronous Generators -- [ ] [PEP 530][]: Asynchronous Comprehensions -- [ ] [PEP 487][]: Simpler customization of class creation -- [ ] [PEP 487][]: Descriptor Protocol Enhancements -- [ ] [PEP 519][]: Adding a file system path protocol -- [ ] [PEP 495][]: Local Time Disambiguation -- [ ] [PEP 529][]: Change Windows filesystem encoding to UTF-8 -- [ ] [PEP 528][]: Change Windows console encoding to UTF-8 -- [ ] [PEP 520][]: Preserving Class Attribute Definition Order -- [ ] [PEP 468][]: Preserving Keyword Argument Order -- [ ] [PEP 523][]: Adding a frame evaluation API to CPython - -Other Language Changes -====================== -- [ ] A `global` or `nonlocal` statement must now textually appear before the first use of the affected name in the same scope. Previously this was a `SyntaxWarning`. -- [ ] It is now possible to set a special method to `None` to indicate that the corresponding operation is not available. For example, if a class sets `__iter__()` to `None`, the class is not iterable. -- [ ] Long sequences of repeated traceback lines are now abbreviated as `"[Previous line repeated {count} more times]"` (see traceback for an example). -- [ ] Import now raises the new exception `ModuleNotFoundError` (subclass of `ImportError`) when it cannot find a module. Code that currently checks for `ImportError` (in try-except) will still work. -- [ ] Class methods relying on zero-argument `super()` will now work correctly when called from metaclass methods during class creation. - -New Modules -=========== -- [ ] `secrets` - -Improved Modules -================ -- [ ] `array` -- [ ] `ast` -- [ ] `asyncio` -- [ ] `binascii` -- [ ] `cmath` -- [ ] `collections` -- [ ] `concurrent.futures` -- [ ] `contextlib` -- [ ] `datetime` -- [ ] `decimal` -- [ ] `distutils` -- [ ] `email` -- [ ] `encodings` -- [ ] `enum` -- [ ] `faulthandler` -- [ ] `fileinput` -- [ ] `hashlib` -- [ ] `http.client` -- [ ] `idlelib and IDLE` -- [ ] `importlib` -- [ ] `inspect` -- [ ] `json` -- [ ] `logging` -- [ ] `math` -- [ ] `multiprocessing` -- [ ] `operator` -- [ ] `os` -- [ ] `pathlib` -- [ ] `pdb` -- [ ] `pickle` -- [ ] `pickletools` -- [ ] `pydoc` -- [ ] `random` -- [ ] `re` -- [ ] `readline` -- [ ] `rlcompleter` -- [ ] `shlex` -- [ ] `site` -- [ ] `sqlite3` -- [ ] `socket` -- [ ] `socketserver` -- [ ] `ssl` -- [ ] `statistics` -- [ ] `struct` -- [ ] `subprocess` -- [ ] `sys` -- [ ] `telnetlib` -- [ ] `time` -- [ ] `timeit` -- [ ] `tkinter` -- [ ] `traceback` -- [ ] `tracemalloc` -- [ ] `typing` -- [ ] `unicodedata` -- [ ] `unittest.mock` -- [ ] `urllib.requests` -- [ ] `urllib.robotparser` -- [ ] `venv` -- [ ] `warnings` -- [ ] `winreg` -- [ ] `winsound` -- [ ] `xmlrpc.client` -- [ ] `zipfile` -- [ ] `zlib` - -Other Improvements -================== -- [x] When `--version` (short form: `-V`) is supplied twice, Python prints `sys.version` for detailed information. - -Deprecated -========== - -New Keywords ------------- -- [ ] `async` and `await` are not recommended to be used as variable, class, function or module names. Introduced by PEP 492 in Python 3.5, they will become proper keywords in Python 3.7. Starting in Python 3.6, the use of `async` or `await` as names will generate a `DeprecationWarning`. - -Deprecated Python Behavior --------------------------- -- [ ] Raising the `StopIteration` exception inside a generator will now generate a `DeprecationWarning` and will trigger a `RuntimeError` in Python 3.7. See PEP 479: Change StopIteration handling inside generators for details. -- [ ] The `__aiter__()` method is now expected to return an asynchronous iterator directly instead of returning an awaitable as previously. Doing the former will trigger a `DeprecationWarning`. Backward compatibility will be removed in Python 3.7. -- [ ] A backslash-character pair that is not a valid escape sequence now generates a `DeprecationWarning`. Although this will eventually become a `SyntaxError`, that will not be for several Python releases. -- [ ] When performing a relative import, falling back on `__name__` and `__path__` from the calling module when `__spec__` or `__package__` are not defined now raises an `ImportWarning`. - -Deprecated Python modules, functions and methods ------------------------------------------------- -- [ ] The `asynchat` has been deprecated in favor of `asyncio`. -- [ ] The `asyncore` has been deprecated in favor of `asyncio`. -- [ ] Unlike other `dbm` implementations, the `dbm.dumb` module creates databases with the `'rw'` mode and allows modifying the database opened with the `'r'` mode. This behavior is now deprecated and will be removed in 3.8. -- [ ] The undocumented `extra_path` argument to the `Distribution` constructor is now considered deprecated and will raise a warning if set. Support for this parameter will be removed in a future Python release. See bpo-27919 for details. -- [ ] The support of non-integer arguments in `getgrgid()` has been deprecated. -- [ ] The `importlib.machinery.SourceFileLoader.load_module()` and `importlib.machinery.SourcelessFileLoader.load_module()` methods are now deprecated. They were the only remaining implementations of `importlib.abc.Loader.load_module()` in `importlib` that had not been deprecated in previous versions of Python in favour of `importlib.abc.Loader.exec_module()`. -- [ ] The `importlib.machinery.WindowsRegistryFinder` class is now deprecated. As of 3.6.0, it is still added to `sys.meta_path` by default (on Windows), but this may change in future releases. -- [ ] Undocumented support of general bytes-like objects as paths in `os` functions, `compile()` and similar functions is now deprecated. -- [ ] Support for inline flags `(?letters)` in the middle of the regular expression has been deprecated and will be removed in a future Python version. Flags at the start of a regular expression are still allowed. -- [ ] OpenSSL 0.9.8, 1.0.0 and 1.0.1 are deprecated and no longer supported. In the future the `ssl` module will require at least OpenSSL 1.0.2 or 1.1.0.. -- [ ] SSL-related arguments like `certfile`, `keyfile` and `check_hostname` in `ftplib`, `http.client`, `imaplib`, `poplib`, and `smtplib` have been deprecated in favor of `context`. -- [ ] A couple of protocols and functions of the `ssl` module are now deprecated. Some features will no longer be available in future versions of OpenSSL. Other features are deprecated in favor of a different API. -- [ ] The `tkinter.tix` module is now deprecated. `tkinter` users should use `tkinter.ttk` instead. -- [ ] The `pyvenv` script has been deprecated in favour of `python3 -m venv`. This prevents confusion as to what Python interpreter `pyvenv` is connected to and thus what Python interpreter will be used by the virtual environment. - -Removed -======= -- [ ] Unknown escapes consisting of `'\'` and an ASCII letter in regular expressions will now cause an error. In replacement templates for `re.sub()` they are still allowed, but deprecated. The `re.LOCALE` flag can now only be used with binary patterns. -- [ ] `inspect.getmoduleinfo()` was removed (was deprecated since CPython 3.3). `inspect.getmodulename()` should be used for obtaining the module name for a given path. -- [ ] `traceback.Ignore` class and `traceback.usage`, `traceback.modname`, `traceback.fullmodname`, `traceback.find_lines_from_code`, `traceback.find_lines`, `traceback.find_strings`, `traceback.find_executable_lines` methods were removed from the `traceback` module. They were undocumented methods deprecated since Python 3.2 and equivalent functionality is available from private methods. -- [ ] The `tk_menuBar()` and `tk_bindForTraversal()` dummy methods in `tkinter` widget classes were removed (corresponding Tk commands were obsolete since Tk 4.0). -- [ ] The `open()` method of the `zipfile.ZipFile` class no longer supports the `'U'` mode (was deprecated since Python 3.4). Use `io.TextIOWrapper` for reading compressed text files in universal newlines mode. -- [ ] The undocumented `IN`, `CDROM`, `DLFCN`, `TYPES`, `CDIO`, and `STROPTS` modules have been removed. They had been available in the platform specific `Lib/plat-*/` directories, but were chronically out of date, inconsistently available across platforms, and unmaintained. The script that created these modules is still available in the source distribution at Tools/scripts/h2py.py. -- [ ] The deprecated `asynchat.fifo` class has been removed. - -[PEP 498]: https://www.python.org/dev/peps/pep-0498 -[PEP 526]: https://www.python.org/dev/peps/pep-0526 -[PEP 515]: https://www.python.org/dev/peps/pep-0515 -[PEP 525]: https://www.python.org/dev/peps/pep-0525 -[PEP 530]: https://www.python.org/dev/peps/pep-0530 -[PEP 487]: https://www.python.org/dev/peps/pep-0487 -[PEP 487]: https://www.python.org/dev/peps/pep-0487 -[PEP 519]: https://www.python.org/dev/peps/pep-0519 -[PEP 495]: https://www.python.org/dev/peps/pep-0495 -[PEP 529]: https://www.python.org/dev/peps/pep-0529 -[PEP 528]: https://www.python.org/dev/peps/pep-0528 -[PEP 520]: https://www.python.org/dev/peps/pep-0520 -[PEP 468]: https://www.python.org/dev/peps/pep-0468 -[PEP 523]: https://www.python.org/dev/peps/pep-0523 From 9f6a90609c442cbfa5130d28846654b8aaa73f43 Mon Sep 17 00:00:00 2001 From: Lamparter Date: Sun, 17 Nov 2024 14:19:00 +0000 Subject: [PATCH 05/26] Migrate documentation to Wiki --- Documentation/building.md | 50 ---- Documentation/differences-from-c-python.md | 269 --------------------- Documentation/feature-symbols.md | 111 --------- Documentation/getting-the-sources.md | 62 ----- Documentation/installing.md | 179 -------------- Documentation/modifying-the-sources.md | 26 -- Documentation/package-compatibility.md | 54 ----- Documentation/upgrading-from-ipy2.md | 257 -------------------- 8 files changed, 1008 deletions(-) delete mode 100644 Documentation/building.md delete mode 100644 Documentation/differences-from-c-python.md delete mode 100644 Documentation/feature-symbols.md delete mode 100644 Documentation/getting-the-sources.md delete mode 100644 Documentation/installing.md delete mode 100644 Documentation/modifying-the-sources.md delete mode 100644 Documentation/package-compatibility.md delete mode 100644 Documentation/upgrading-from-ipy2.md diff --git a/Documentation/building.md b/Documentation/building.md deleted file mode 100644 index 3a8879a29..000000000 --- a/Documentation/building.md +++ /dev/null @@ -1,50 +0,0 @@ -# Building IronPython3 - -To build IronPython3 you will need the [.NET SDK (minimum v6.0.100)](https://dotnet.microsoft.com/download/visual-studio-sdks). - -See [Getting the Sources](getting-the-sources.md) for information on getting the source for IronPython3. - -## Building from Visual Studio - -Visual Studio 2022 v17.0 or above is required to build IronPython3. - - * Open the `IronPython.sln` solution file - * Select the configuration options (Release, Debug, etc.) - * Press Ctrl+Shift+B or F6 to build the solution - -## Building from the command line - -IronPython3 uses PowerShell to run the build and testing from the command line. You can either use a PowerShell directly, or prefix the commands below with `powershell` on Windows, or `pwsh` on Linux/macOS. - -On Linux/macOS you will need to install [PowerShell](https://github.com/PowerShell/PowerShell/releases) - -Change the working directory to the path where you cloned the sources and run `./make.ps1` - -By default, with no options, `make.ps1` will build the `Release` mode binaries. If you would like to build `Debug` binaries, you can run `./make.ps1 debug` - -Other options available for `make.ps1` are - -``` --configuration (debug/release) The configuration to build for --platform (x86/x64) The platform to use in running tests --runIgnored Run tests that are marked as ignored in the .ini manifests --frameworks A comma separated list of frameworks to run tests for - (use nomenclature as is used in msbuild files for TargetFrameworks) -``` - -There are also other targets available for use with packaging and testing, most come in debug and release (default) versions, such as `package-debug` and `package` - -``` -package Creates packages supported by the current platform -stage Stages files ready for packaging -test-* Runs tests from `all` categories, `ironpython` specific tests, - `cpython` tests from the CPython stdlib test suite -``` - -If the build is successful the binaries are stored in `ironpython3/bin/{Configuration}/{TargetFramework}`. - -## Running - -The standard library is not copied over to the `bin` folder during the build process, it lives in `Src/StdLib/Lib`. -- When running the `Release` configuration executable, you should set the environment variable `IRONPYTHONPATH` to this folder. -- When running the `Debug` configuration executable, this folder is automatically added to `sys.path`. diff --git a/Documentation/differences-from-c-python.md b/Documentation/differences-from-c-python.md deleted file mode 100644 index 07e4fdbb0..000000000 --- a/Documentation/differences-from-c-python.md +++ /dev/null @@ -1,269 +0,0 @@ -This page documents various differences between IronPython and CPython. Since IronPython is under active development, any of the differences described here may change or disappear in the future: - -- [Environment Variables](#environment-variables) -- [COM Interaction](#com-interaction) -- [Strings](#strings) -- [Interaction with the Operating System](#interaction-with-the-operating-system) -- [Codecs](#codecs) -- [Source File Encoding](#source-file-encoding) -- [Recursion](#recursion) - -# Environment Variables - -* `IRONPYTHONSTARTUP` is used instead of `PYTHONSTARTUP` - -* `IRONPYTHONPATH` is used instead of `PYTHONPATH` - -# COM Interaction - -* Interaction with COM objects is handled by the CLR rather than a python library binding to the native COM dlls. - -# Strings - -* `str` objects are represented in UTF-16 (like all .NET strings) rather than UTF-32 used by CPython. - -This has a few visible consequences if characters ouside of the Basic Multilingual Plane (BMP) are used (that is, characters with Unicode code points above `U+FFFF`). A few examples below illustrate the differences. - -Let's take a Unicode character U+1F70B, '🜋'. In CPython, it is represented by a single character: - -_CPython_ -``` ->>> len('\U0001f70b') -1 ->>> str('\U0001f70b') -'🜋' -``` - -In IronPython, it is represented by a pair of surrogate characters U+D83D and U+DF0B: - -_IronPython_ -``` ->>> len('\U0001f70b') -2 ->>> str('\U0001f70b') -'\ud83d\udf0b' -``` - -In **both** cases, however, the string containing such character is printed out correctly, since `print` will transcode the string from its internal representation to whichever encoding is used by the console or file (usually UTF-8): - -_CPython_ and _IronPython_ -``` -print('\U0001f70b') -'🜋' -``` - -Any surrogate pair in IronPython strings represents one logical character. CPython, however, sees a surrogate pair as two invalid characters. - -_IronPython_ -``` ->>> '\ud83d\udf0b' -'\ud83d\udf0b' ->>> print('\ud83d\udf0b') -🜋 ->>> '\ud83d\udf0b'.encode('utf-8') -b'\xf0\x9f\x9c\x8b' ->>> '\U0001f70b'.encode('utf-8') -b'\xf0\x9f\x9c\x8b' -``` - -_CPython_ -``` ->>> '\ud83d\udf0b' -'\ud83d\udf0b' ->>> print('\ud83d\udf0b') -Traceback (most recent call last): - File "", line 1, in -UnicodeEncodeError: 'utf-8' codec can't encode characters in position 0-1: surrogates not allowed -'\ud83d\udf0b'.encode('utf-8') -Traceback (most recent call last): - File "", line 1, in -UnicodeEncodeError: 'utf-8' codec can't encode characters in position 0-1: surrogates not allowed -``` - -CPython requires use of `'surrogatepass'` error handler to let those pairs through. Note however, that they are still being treated as two separate characters. IronPython encodes the pair as if it were one character. - -_CPython_ -``` ->>> '\ud83d\udf0b'.encode('utf-8','surrogatepass') -b'\xed\xa0\xbd\xed\xbc\x8b' ->>> '\U0001f70b'.encode('utf-8') -b'\xf0\x9f\x9c\x8b' -``` - -The `'surrogatepass'` error handler is still needed in IronPython to handle surrogate characters that do not form a valid surrogate pair: - -_IronPython_ -``` -print('\ud83d\udf0b') -🜋 ->>> print('\ud83d\udf0b'[::-1]) -Traceback (most recent call last): - File "", line 1, in -UnicodeEncodeError: 'cp65001' codec can't encode character '\udf0b' in position 0: Unable to translate Unicode character \\uDF0B at index 0 to specified code page. ->>> print('\ud83d\udf0b'[::-1].encode('utf-8','surrogatepass')) -b'\xed\xbc\x8b\xed\xa0\xbd' -``` - -_CPython_ -``` ->>> print('\ud83d\udf0b') -Traceback (most recent call last): - File "", line 1, in -UnicodeEncodeError: 'utf-8' codec can't encode characters in position 0-1: surrogates not allowed ->>> print('\ud83d\udf0b'[::-1]) -Traceback (most recent call last): - File "", line 1, in -UnicodeEncodeError: 'utf-8' codec can't encode characters in position 0-1: surrogates not allowed ->>> print('\ud83d\udf0b'[::-1].encode('utf-8','surrogatepass')) -b'\xed\xbc\x8b\xed\xa0\xbd' -``` - -# Interaction with the Operating System - -* Environment variables are decoded using the `'replace'` error handler, rather than the `'surrogateescape'` error handler used by CPython. - -This is how .NET libraries handle encoding errors in the system. The difference is only visible on Posix systems that have environment variables defined using a different encoding than the encoding used by the system (Windows environment variables are always in UTF-16, so no conversion takes place when accessed as Python `str` objects). - -Assume that a Linux system is configured to use UTF-8. Under bash: - -``` -$ python -c 'f=open("test.sh","w",encoding="latin-1");print("NAME=\"André\"",file=f)' -$ source test.sh -$ export NAME -``` - -This creates an environment variable that is encoded using Latin-1 encoding, rather than the system encoding. CPython will escape the invalid byte 0xe9 (letter 'é' in Latin-1) in a lone surrogate 0xdce9, which is still an invalid Unicode character. - -_CPython_ -``` ->>> import os ->>> os.environ["NAME"] -'Andr\udce9' ->>> print(os.environ["NAME"]) -Traceback (most recent call last): - File "", line 1, in -UnicodeEncodeError: 'utf-8' codec can't encode character '\udce9' in position 4: surrogates not allowed -``` - -IronPython will replace the invalid byte with U+FFFD, the Unicode replacement character, which is a valid and printable character. - -_IronPython_ -``` ->>> import os ->>> os.environ["NAME"] -'Andr�' ->>> print(os.environ["NAME"]) -Andr� ->>> hex(ord(os.environ["NAME"][-1])) -'0xfffd' -``` - -The CPython representation is not printable, but can be safely encoded back to the original form using `'surrogateescape'` (default when dealing with the OS environment): - -_CPython_ -``` ->>> os.environ["PATH"] = os.environ["PATH"] + ":/home/" + os.environ["NAME"] + "/bin" ->>> import posix ->>> posix.environ[b"PATH"] -b'/bin:/usr/bin:/usr/local/bin:/home/Andr\xe9/bin' ->>> os.environ["NAME"].encode("utf-8","surrogateescape") -b'Andr\xe9' -``` - -The IronPython representation is printable, but the original byte value is lost: - -_IronPython_ -``` ->>> os.environ["NAME"].encode("utf-8","surrogateescape") -b'Andr\xef\xbf\xbd' -``` - -# Codecs - -* Some single-byte codecs may have unused positions in their codepage. There are differences between how CPython and IronPython (and .NET) handle such cases. - -A simple example is encoding Windows-1252. According to the information on Microsoft's and the Unicode Consortium's websites, positions 81, 8D, 8F, 90, and 9D are unused; however, the Windows API `MultiByteToWideChar` maps these to the corresponding C1 control codes. The Unicode "best fit" mapping [documents this behavior](https://www.unicode.org/Public/MAPPINGS/VENDORS/MICSFT/WindowsBestFit/bestfit1252.txt). CPython will treat those bytes as invalid, while IronPython will map them to the "best fit" Unicode character: - -_CPython_ -``` ->>> b'\x81'.decode('windows-1252') -Traceback (most recent call last): - File "", line 1, in - File "/opt/anaconda3/envs/py34/lib/python3.4/encodings/cp1252.py", line 15, in decode - return codecs.charmap_decode(input,errors,decoding_table) -UnicodeDecodeError: 'charmap' codec can't decode byte 0x81 in position 0: character maps to ->>> b'\x81'.decode('windows-1252','surrogateescape') -'\udc81' -``` - -_IronPython_ -``` ->>> b'\x81'.decode('windows-1252') -'\x81' ->>> b'\x81'.decode('windows-1252','surrogateescape') -'\x81' -``` - -The same difference in behavior can be observed during encoding: - -_CPython_ -``` ->>> '\x81'.encode('windows-1252') -Traceback (most recent call last): - File "", line 1, in - File "/opt/anaconda3/envs/py34/lib/python3.4/encodings/cp1252.py", line 12, in encode - return codecs.charmap_encode(input,errors,encoding_table) -UnicodeEncodeError: 'charmap' codec can't encode character '\x81' in position 0: character maps to -``` - -_IronPython_ -``` ->>> '\x81'.encode('windows-1252') -b'\x81' -``` - -* When using the UTF-7 encoding, IronPython (and .NET) always terminates the modified Base64 encoded blocks with a '-' while CPython omits the '-' if allowed. - -The UTF-7 standard allows encoders for some freedom of implementation. One optionality allowed in UTF-7 is how to end a sequence encoded in the modified Base64 code. In principle, `+` marks the start of the sequence, and `-` is the terminator. However, it is allowed to omit the terminating `-` if the next character unambiguously does not belong to the encoded Base64 block. CPython chooses to drop the terminating `-` in such cases, while IronPython will always terminate Base64-encoded blocks with a `-`: - -_CPython_ -``` ->>> 'abc:~~:zyz'.encode('utf-7') -b'abc:+AH4Afg:zyz' -``` - -_IronPython_ -``` ->>> 'abc:~~:zyz'.encode('utf-7') -b'abc:+AH4Afg-:zyz' -``` - -Note that both forms are fully interchangeable; IronPython will correctly decode what CPython encoded and vice versa. - -# Source File Encoding - -* Widechar Unicode encodings are supported as source file encoding, in addition to standard Python encodings. - -The default source file encoding is UTF-8. This also applies to bytestrings used within the program (processed by `compile`, `eval`, or `exec`). The source file encoding can be explicitly specified, and possibly changed, in one of the two ways: - - 1. By declaring the encoding in a Python comment in one of the first two lines — in accordance with [PEP-263](https://www.python.org/dev/peps/pep-0263/). - 2. By a byte-order-mark (BOM) — only for Unicode encodings. - -CPython recognizes only UTF-8 BOM. IronPython recognizes BOM in UTF-8, UTF-16LE, UTF-16BE, UTF-32LE, and UTF-32BE. - -If both BOM and PEP-263 methods are used simultaneously in the same file, they should be specifying the same encoding. If the PEP-263 encoding does not match the BOM, then: - - * In case of UTF-8 BOM, an error will be reported (by both CPython and IronPython). - * In case of other BOMs, the encoding specified in the PEP-263 comment is silently ignored. - -# Recursion - -By default, instead of raising a `RecursionError` when the maximum recursion depth is reached, IronPython will terminate with a `StackOverflowException`. You can enable the recursion limit in IronPython in a number of ways: - - 1. From the command line: `ipy -X MaxRecursion=100`. - 2. In hosted scenarios: `Python.CreateEngine(new Dictionary() { { "RecursionLimit", 100 } });`. - 3. From Python: `sys.setrecursionlimit(100)`. - -*There is a significant performance cost when the recursion limit is enabled*. - -Note that IronPython 3.4 adopts the CPython 3.5 behavior and throws a `RecursionError` instead of a `RuntimeError`. diff --git a/Documentation/feature-symbols.md b/Documentation/feature-symbols.md deleted file mode 100644 index c179e1da1..000000000 --- a/Documentation/feature-symbols.md +++ /dev/null @@ -1,111 +0,0 @@ -# Feature Symbols - -Feature Symbols (named FEATURE_{feature name}, all caps) are compilation symbols defined for features whose availability vary across platforms that IronPython supports. The symbols are defined in Build/{framework}.props file, which get included by all .csproj files that contribute to IronPython. - -**The following list needs a major update** - -The following symbols are currently used: -### FEATURE_APARTMENTSTATE -System.Threading.ApartmentState - -### FEATURE_ASSEMBLY_GETFORWARDEDTYPES -System.Reflection.Assembly.GetForwardedTypes - -### FEATURE_ASSEMBLY_RESOLVE -Runtime assembly resolution (System.AppDomain.AssemblyResolve event). - -### FEATURE_ASSEMBLYBUILDER_DEFINEDYNAMICASSEMBLY -System.Reflection.Emit.AssemblyBuilder.DefineDynamicAssembly - -### FEATURE_ASSEMBLYBUILDER_SAVE -System.Reflection.Emit.AssemblyBuilder.Save - -### FEATURE_CODEDOM -System.CodeDom - -### FEATURE_COM - -### FEATURE_CONFIGURATION -Configuration files (System.Configuration). - -### FEATURE_CTYPES - -### FEATURE_CUSTOM_TYPE_DESCRIPTOR -System.ComponentModel.ICustomTypeDescriptor interface. - -### FEATURE_EXCEPTION_STATE -System.Threading.ThreadAbortException.ExceptionState - -### FEATURE_FILESYSTEM -Full file system (Directory, File, Path, FileStream, etc.) - -### FEATURE_FULL_CRYPTO - -### FEATURE_FULL_NET - -### FEATURE_LAMBDAEXPRESSION_COMPILETOMETHOD -System.Linq.Expressions.LambdaExpression.CompileToMethod - -### FEATURE_LCG - -### FEATURE_LOADWITHPARTIALNAME -System.Reflection.Assembly.LoadWithPartialName - -### FEATURE_METADATA_READER -DLR metadata reader available. - -### FEATURE_MMAP -System.IO.MemoryMappedFiles - -### FEATURE_NATIVE -Native code interop: P/Invokes, CTypes, etc. - -### FEATURE_OSPLATFORMATTRIBUTE -System.Runtime.Versioning.OSPlatformAttribute - -### FEATURE_PDBEMIT -Ability to emit PDB files. - -### FEATURE_PIPES - -### FEATURE_PROCESS -Processes, AppDomains, process-wide environment variables. - -### FEATURE_REFEMIT -Reflection.Emit. - -### FEATURE_REFEMIT_FULL - -### FEATURE_REGISTRY - -### FEATURE_REMOTING -Remoting (MarshalByRefObject). - -### FEATURE_RUNTIMEINFORMATION -System.Runtime.InteropServices.RuntimeInformation - -### FEATURE_SECURITY_RULES -System.Security.SecurityRuleSet and related (e.g. System.Security.SecurityRulesAttribute) - -### FEATURE_SERIALIZATION -Serialization - Serializable attribute, ISerializable interface. - -### FEATURE_STACK_TRACE -System.Diagnostics.StackTrace, System.Diagnostics.StackFrame. - -### FEATURE_SYNC_SOCKETS -System.Net.Sockets. - -### FEATURE_THREAD -Threads, ThreadAbortException. - -### FEATURE_TYPE_EQUIVALENCE -System.Type.IsEquivalentTo - -### FEATURE_TYPECONVERTER -System.ComponentModel.TypeConverter and TypeConverterAttribute types. - -### FEATURE_WPF - -### FEATURE_XMLDOC -XML documentation available at runtime. diff --git a/Documentation/getting-the-sources.md b/Documentation/getting-the-sources.md deleted file mode 100644 index b5bd5e4a9..000000000 --- a/Documentation/getting-the-sources.md +++ /dev/null @@ -1,62 +0,0 @@ -The main IronPython3 git repository is at [http://github.com/IronLanguages/ironpython3](http://github.com/IronLanguages/ironpython3). - -## Downloading the sources - -You can [download a zipped copy](http://github.com/IronLanguages/ironpython3/zipball/main) of the latest IronPython3 sources as well. - -### Installing GIT - -The following links include resources for installing and using GIT: - * [GitHub guides](http://help.github.com/) - * [GIT documentation](http://www.kernel.org/pub/software/scm/git/docs/git.html) - If you have never used GIT, reading the [tutorial](http://www.kernel.org/pub/software/scm/git/docs/gittutorial.html) first will be a big help to finding your way around. - * [Cheat sheet](http://cheat.errtheblog.com/s/git) - Quick reference for commonly used commands - * [Collaborative Github Workflow](http://www.eqqon.com/index.php/Collaborative_Github_Workflow) - very good description of the workflow and tips and tricks when contributing to a project hosted on GitHub. - * [Jimmy's Cheatsheet](http://tinyurl.com/jimmygitcheat) - -### Creating a local GIT repository - -You will first need to fork the IronPython3 project. [Creating a fork](https://help.github.com/fork-a-repo/) is recommended as it will allow you to contribute patches back easily. Click the "Fork" button on [https://github.com/IronLanguages/ironpython3/](https://github.com/IronLanguages/ironpython3/). This should create your personal fork, with a web URL like http://github.com/janedoe/ironpython3 (where janedoe is your github username). - -You can now use the git command-line client with many Linux distributions, Mac OS, Cygwin, and Windows (msysgit) to get the sources onto your local computer using the following commands: - -``` -git config --global branch.autosetupmerge true -git config --global user.name "Jane Doe" -git config --global user.email janedoe@example.com - -git clone git@github.com:janedoe/ironpython3.git -cd ironpython3 -git remote add ironpython3 git://github.com/IronLanguages/ironpython3.git -git pull ironpython3 main -``` - -At a later date, to get the latest updates from the IronPython3 project, run the following command in the ironpython3 directory created above: - -``` -git pull ironpython3 main -``` - -If there is a merge conflict, edit the unmerged files to remove the conflict markers, and then run the following command: - -``` -git commit -a -``` - -To push your changes back to your fork and make them public, use `git push`. - -### Working without a fork - -You can skip creating a fork if you only want to browse the sources. In that case, you can clone the project directly as such: -``` -git clone git://github.com/IronLanguages/ironpython3.git -git pull -``` - -### Initialize submodules - -The DLR (Dynamic Language Runtime) is a submodule of the ironpython3 repository, you need to initialize after cloning the repository. -``` -git submodule update --init -``` - -For more information there is an excellent tutorial on [getting started with git](http://kylecordes.com/2008/04/30/git-windows-go/) diff --git a/Documentation/installing.md b/Documentation/installing.md deleted file mode 100644 index 7371f20c5..000000000 --- a/Documentation/installing.md +++ /dev/null @@ -1,179 +0,0 @@ -# Installing IronPython Released Binaries - -IronPython can be used as a standalone interpreter, or embedded within another .NET application. For embedding, the recommended approach is to install IronPython within the target project using NuGet. This document describes various ways of installing the standalone interpreter on the target system. Once installed, IronPython is invocable from the command line as `ipy`. Use `ipy -h` for a list of available commadline options. Use `ipy -VV` to produce version information for reporting issues. - -## IronPython on .NET (Core) - -Since .NET is a cross-platform framework, the instructions in this section apply to all supported operating systems (Windows, Linux, macOS), unless explicitly indicated. - -### .NET SDK - -If the target system already has a full .NET SDK installed, the most straightforward method to install a standalone IronPython interpreter is by using [`dotnet tool`](https://learn.microsoft.com/en-us/dotnet/core/tools/global-tools). - -#### _Global Tool_ - -"Global" .NET tool means one installation for the current user. It is not available to other users in the system. Install IronPython with: - -``` -dotnet tool install --global ironpython.console -``` - -The switch `--global` can be abbreviated to `-g`. The `ipy` program will be installed in `~/.dotnet/tools`, together with the Python Standard Library for IronPython. The directory `~/.dotnet/tools` should be added to the search path for the user (AKA `PATH` environment variable), if not yet done. - -Note that any additional Python packages installed using `ipy -m pip` from this location will be installed inside that directory, hence being "global" for the user. - -#### _Project Tool_ - -IronPython can be installed as a tool local to an existing .NET project. Navigate to the root directory of the .NET project and make sure that the tool manifest file is already present(`./.config/dotnet-tools.json`). If not, create a new empty tool manifest with: - -``` -dotnet new tool-manifest -``` - -There is one tools manifest for all .NET tools configured for a given project, tracking all .NET tools used within the project. Consider adding `dotnet-tools.json` to the source control management system (like _git_). - -Install IronPython and Python Standard Library with: - -``` -dotnet tool install ironpython.console -``` - -and invoke it with `dotnet ipy` from within any folder within the project. - -**NOTE**: Any additional packages installed with `dotnet ipy -m pip` are **NOT** local to the project, but installed in a location shared by all .NET project using `ipy ` as a local tool (`~/.nuget/packages/ironpython.console`). - -If the project is cloned onto another system and the tools manifest is already present and contains the reference to `ironpython.console`, all that is needed to install `ipy` locally is: - -``` -dotnet tool restore -``` - -#### _Virtual Environment_ - -The third way of installing IronPython as a .NET tool is to specify the installation directory explicitly: - -``` -dotnet tool install ironpython.console --tool-path /path/to/install/directory -``` - -This installs IronPython, together with the matching Python Standard Library, in a way that is independent from any other IronPython installations on the system, effectively creating an equivalent of a Python virtual environment. The target directory is created and will contain executable `ipy` (`ipy.exe` on Windows). When installed by the admin in a location accessible by all users (e.g. "C:\IronPython", or "/usr/local/bin"), it can serve as a "system-wide" installation. - -Any additional packages installed with `/path/to/install/directory/ipy -m pip` are only visible for this particular installation. - -### .NET Runtime - -If the target system does not have .NET SDK installed, but does have a .NET Runtime installed (i.e `dotnet --version` works), a way to install IronPython is to use the zip file published on the project's [release page](https://github.com/IronLanguages/ironpython3/releases/latest). - -Installations from the zip file are self-contained, so in a sense work like a Python virtual environment. For PowerShell users, the zip archive also contains script `Enter-IronPythonEnvironment.ps1` that works similarly to Anaconda's `Enter-CondaEnvironment.ps1` or CPython's `activate.ps1`. Use `help` on this file for detailed usage information. - -#### _Manual_ - -Download and unzip `IronPython.3.X.Y.zip` (`X` and `Y` being the minor and patch version numbers). The unzipped directory contains several .NET Runtime version-specific subdirectories and a subdirectory `lib`. Pick a subdirectory that matches the .NET Runtime version installed on your system (or lower), and **move** subdirectory `lib` into that directory. IronPython can then be launched with - -``` -dotnet /path/to/unzipped/netXXX/ipy.dll -``` - -#### _Scripted_ - -The zip file contains a helper PowerShell script to install IronPython properly in a designated location and creates a launcher script. In this way one zip file can "seed" multiple virtual environments, each starting "blank" that is, with only the Python Standard Library present. - -``` -/path/to/unzipped/scripts/Install-IronPython.ps1 -Path ~/ipyenv -ZipFile ~/Downloads/IronPython.3.X.Y.zip -``` - -Use Powershell's `help` command on the script for information about available options and switches. - -The script is also available online, so it can be downloaded and invoked without unzipping the archive first. - -``` -PS> Invoke-WebRequest https://raw.githubusercontent.com/IronLanguages/ironpython3/main/Src/Scripts/Install-IronPython.ps1 -OutFile ./Install-IronPython.ps1 -PS> ./Install-IronPython ~/ipyenv ~/Downloads/IronPython.3.X.Y.zip -PS> ~/ipyenv/Enter-IronPythonEnvironment -«ipyenv» PS> ipy -IronPython 3.4.0 (3.4.0.1000) -[.NETCoreApp,Version=v6.0 on .NET 6.0.12 (64-bit)] on win32 -Type "help", "copyright", "credits" or "license" for more information. ->>> -``` - -## IronPython on .NET Framework/Mono - -### Windows - -IronPython for .NET Framework requires .NET Framework version 4.6.2 or higher, which comes preinstalled on modern versions of Windows. To install IronPython, download the `.msi` file from the project's [release page](https://github.com/IronLanguages/ironpython3/releases/latest) and execute it. The installation of `.msi` registers IronPython in the System Registry in compliance with [PEP 514](https://peps.python.org/pep-0514/) so that other tools may detect and use it. - -Alternatively, use _Chocolatey_ package manager: - -``` -choco install ironpython -``` - -### Linux (Debian-like) - -On Linux, Mono provides the necessary .NET Framework. First install Mono following installation instructions from the [Mono Project page](https://www.mono-project.com/download/stable/#download-lin). After installation, verify that command `mono` is available at the shell prompt, with, e.g. `mono --version`. - -Then download the `.deb` package from the project's [release page](https://github.com/IronLanguages/ironpython3/releases/latest). - -Finally install the package using `dpkg`, e.g.: - -``` -dpkg -i ~/Downloads/ironpython_3.X.Y.deb -``` - -### macOS - -On macOS (AKA OSX, Darwin), Mono provides the necessary .NET Framework. First install Mono following installation instructions from the [Mono Project page](https://www.mono-project.com/download/stable/#download-mac). After installation, verify that command `mono` is available at the shell prompt, with, e.g. `mono --version`. - -Then download the `.pkg` installer from the project's [release page](https://github.com/IronLanguages/ironpython3/releases/latest) and execute it. The IronPython installation is placed in `/Library/Frameworks/IronPython.framework/Versions/3.X.Y` (`X` and `Y` being the minor and patch version numbers). It can be run with: - -``` -mono /Library/Frameworks/IronPython.framework/Versions/3.X.Y/bin/ipy.exe -``` - -Note that Mono comes with its own (old, obsolete, and unsupported) version of IronPython and a launcher script `ipy` in Mono's commands directory (`/Library/Frameworks/Mono.framework/Versions/Current/Commands/ipy`). Since Mono's command directory is by default added to the command search path, simply running `ipy` from the command line will most likely pick up the Mono version. This version reports version number 3.0.0.0 and is backed by Python StdLib 2.7. To verify if this is the case, run: - -```shell -$ which ipy -/Library/Frameworks/Mono.framework/Versions/Current/Commands/ipy -$ ipy -V -IronPython 3.0 3.0.0.0 on 6.12.0.188 (2020-02/ca8abcb6bc4 Thu Oct 13 14:26:22 EDT 2022) -``` - -It is recommended to create one's own launcher script launching the newer IronPython version and to put it before Mono's `ipy` on the search path. - -# Installing Non-Released Versions - -After a release, the development of IronPython continues so it is possible that a bug or a feature that is important to you was handled after the latest release. As each commit to the main project branch creates precompiled artifacts, it is still possible to install the relevant (or latest development) version of IronPython without the need to compile the whole project from scratch. - -Go to the project's [_Actions_ page](https://github.com/IronLanguages/ironpython3/actions) and find the commit you are interested in. Or simply find the topmost commit to `main` that has all tests passing. The _Status_ and _Branch_ filters in the top bar are helpful to narrow the list down. Then click on the commit hyperlink to access the CI run summary. At the bottom of that page there is artifact `packages`, which contains all binary artifacts the project produces. Download it and unzip. Choose the right package for your needs and follow instructions above for the officially released artifacts. For convenience, here is a table with usable packages: - -| Artifact | Framework | Operating System | -| -------------------- | ------------------------------ | ----------------------------------- | -| IronPython.3.X.Y.zip | all supported | all supported | -| IronPython-3.X.Y.msi | .NET Framework 4.6.2 or higher | Windows | -| ironpython_3.X.Y.deb | Mono 6.12 or higher | Linux (Debian, Ubuntu, and similar) | -| IronPython-3.X.Y.pkg | Mono 6.12 or higher | macOS | - - -# Installing from Sources - -To build and install IronPython from sources, first follow instructions in [_Getting the Sources_](https://github.com/IronLanguages/ironpython3/blob/main/Documentation/getting-the-sources.md) and [_Building IronPython3_](https://github.com/IronLanguages/ironpython3/blob/main/Documentation/building.md). - -When the command `./make.ps1 debug` completes successfully, runnable and usable `ipy` executables are available in subdirectories of `./bin/Debug`. To run executables from the release configuration (produced by a successful run of `./make.ps1`), first set environment variable `IRONPYTHONPATH`. - -If those executables test out successfully, the binaries can be installed outside the project directory, or on another system. Create the installation artifacts with: - -``` -./make.ps1 package -``` - -The artifacts are placed in directory `./Package/Release/Packages/IronPython-3.X.Y`. Pick a package suitable for your installation target and follow instructions above for the officially released packages. - -Note: as a convenience, if you run `Install-IronPython.ps1` directly from directory `./Src/Scripts` to install IronPython from the zip file, there is no need to pass the location to the zip file; the script finds it automatically using the relative path. - -Installation example: - -``` -./Src/Scripts/Install-IronPython.ps1 /path/to/install/directory -framework net462 -``` diff --git a/Documentation/modifying-the-sources.md b/Documentation/modifying-the-sources.md deleted file mode 100644 index 7016f075d..000000000 --- a/Documentation/modifying-the-sources.md +++ /dev/null @@ -1,26 +0,0 @@ -# TDD - -Bug fixes should be accompanied by a test that shows that the bug has been fixed. If the bug fix is fixing something that is covered by a test in the C Python test suite (Src\StdLib\Lib\test) and that test is not currently enabled, try enabling the test in Src\IronPythonTest\Cases\*.ini depending on the type of test it is. - -Most PR's will not be accepted if there is not a test included. - -# Coding conventions - - * We have a .editorconfig file with the coding conventions used in the project. Please use an editor that honors these settings. - - * Use [.NET Framework conventions for all identifiers](https://docs.microsoft.com/en-us/dotnet/standard/design-guidelines/naming-guidelines). - * There is no specific guideline for naming private fields in this document; we prefix field names with underscores (e.g. private string _fooBar;) so that use of the fields is easily distinguishable as a field access as opposed to a local variable access. - * If you're not sure about some convention, try to find out in the rest of the IronPython code or ask in the list. - * Use `/*!*/` for method parameters and instance fields that should never be null. [Spec# annotations](http://research.microsoft.com/specsharp). - * Do not use public fields (Base::algorithm, buffer). Use properties if it is necessary to expose the field or private/internal visibility otherwise. - * Use `readonly` if the field is not mutated after the object is constructed. - * Auto properties are to be used when possible instead of private fields with wrapping properties. - * String interpolation should use used instead of calls to `String.Format` - -# Validating the changes - -The following commands will build and run all the tests that are required to pass. If you get any failures, do report them to the mailing-list to see if they are expected or not. This command can usually run without any failures. - -``` -./make.ps1 test-all -``` \ No newline at end of file diff --git a/Documentation/package-compatibility.md b/Documentation/package-compatibility.md deleted file mode 100644 index 0ed38bc10..000000000 --- a/Documentation/package-compatibility.md +++ /dev/null @@ -1,54 +0,0 @@ -# Package compatibility - -Note that IronPython does not currently support packages which are C extension modules. - -## numpy - -:warning: Not supported - C extension module. - -## pandas - -:warning: Not supported - requires `numpy`. - -## pytest (4.6.11) - -To install: -``` -ipy -m pip install pytest==4.6.11 typing==3.10.0.0 -``` - -The package fails with (probably the same issue as https://github.com/IronLanguages/ironpython3/issues/1212): -``` -SystemError: Cannot access a closed file. -``` - -Edit `_pytest/capture.py` and replace: -```py -with f: - tmpfile = safe_text_dupfile(f, mode="wb+") -``` -with: -```py -tmpfile = EncodedFile(f, getattr(f, "encoding", "utf-8")) -``` - -## requests (2.21.0) - -To install: -``` -ipy -m pip install requests==2.21.0 -``` - -## sympy (1.4) - -To install: -``` -ipy -m pip install sympy==1.4 -``` - -The above will also automatically install `mpmath` 1.2.1 if not yet installed. - -`sympy` comes with an interactive console, which can be started with: -``` -ipy -m isympy -``` diff --git a/Documentation/upgrading-from-ipy2.md b/Documentation/upgrading-from-ipy2.md deleted file mode 100644 index 4f59586da..000000000 --- a/Documentation/upgrading-from-ipy2.md +++ /dev/null @@ -1,257 +0,0 @@ -# Upgrading from IronPython 2 to 3 - -IronPython 3.4 uses Python 3.4 syntax and standard libraries and so your Python code will need to be updated accordingly. There are numerous tools and guides available on the web to help porting from Python 2 to 3. - -## Binary compatibility - -The IronPython 3 binaries are not compatible with the IronPython 2 binaries. Modules compiled with `clr.CompileModules` using IronPython 2 are not compatible and will need to be recompiled using IronPython 3. - -## Checking for IronPython - -In an effort to improve compatibility, `sys.platform` no longer returns `cli`. If you wish to check if you're running on IronPython the recommended pattern is to check that `sys.implementation.name` is equal to `ironpython`: - -```Python -if sys.implementation.name == "ironpython": - print("IronPython!") -``` - -## `None` is a keyword - -`None` is a keyword in Python 3 and trying to access a member called `None` will raise a `SyntaxError`. Since this name is frequently used in .NET code (e.g. in enums), code trying to use it is going to throw. You can use alternate syntax in order to access the .NET member, for example `getattr(x, "None")` or an accessor for enums `MyEnum["None"]`. - -```python -# IronPython 2 -System.StringSplitOptions.None -``` - -```python -# IronPython 3 -System.StringSplitOptions["None"] -``` - -Similarly, `True` and `False` are also keywords in Python 3. - -## Redirecting output - -With IronPython 2, standard output was written to the runtime's `SharedIO.OutputWriter` (which was `Console.Out` by default). This is no longer the case with IronPython 3 where the standard output is a binary stream. The output is now written to runtime's `SharedIO.OutputStream`. Similarly, standard input and error are now using `SharedIO.InputStream` and `SharedIO.ErrorStream` respectively. - -Because of this, using a `TextWriter` to capture output will no longer work. As a workaround, in order to use a `TextWriter` as the main method of redirection, one could wrap the writer inside a stream (for example, see [`TextStream`][TextStream]). - -```c# -// IronPython 2 -var engine = Python.CreateEngine(); -var textWriter = new MyTextWriter(); -// no longer works in IronPython 3! -engine.Runtime.IO.RedirectToConsole(); -Console.SetOut(textWriter); -``` - -```c# -// IronPython 3 -var engine = Python.CreateEngine(); -var textWriter = new MyTextWriter(); -engine.Runtime.IO.SetOutput(new TextStream(textWriter), textWriter); -``` - -Another way of achieving the redirection behavior similar to IronPython 2 is to set engine option `ConsoleSupportLevel` to `SupportLevel.Basic`. IronPython 3 still uses binary streams for standard input and output but **all three** standard streams are set to use `TextStream`, forwarding to the corresponding writers/reader. - -```c# -// IronPython 3 -var engine = Python.CreateEngine(new Dictionary { - { "ConsoleSupportLevel", Microsoft.Scripting.Runtime.SharedIO.SupportLevel.Basic }, -}); -var textWriter = new MyTextWriter(); -// works again! -engine.Runtime.IO.RedirectToConsole(); -Console.SetOut(textWriter); -``` - -This method is particularly useful when embedding the IronPython 3 engine in a host that sets console's writers/reader before the engine is created and the host's code is not accessible to the user (for instance, scripting in [LINQPad]). - -```c# -// IronPython 3 in LINQPad -var engine = Python.CreateEngine(new Dictionary { - { "ConsoleSupportLevel", Microsoft.Scripting.Runtime.SharedIO.SupportLevel.Basic }, -}); -engine.Execute("print('abc')"); // shows output in the "Results" pane -dynamic ans = engine.Execute("input()"); // pauses the script and asks for input at the bottom of the "Results" pane; terminate your input with Ctrl+Z, Enter -``` - -[TextStream]: https://github.com/IronLanguages/dlr/blob/main/Src/Microsoft.Scripting/Utils/TextStream.cs -[LINQPad]: https://www.linqpad.net/ - -## `int` Type - -One of the major backward incompatible changes in Python 3 is [PEP 237 – Unifying Long Integers and Integers][PEP 0237]: Essentially, `long` renamed to `int`. That is, there is only one built-in integral type, named `int`; but it behaves mostly like the old `long` type. From the pure Python perspective this means that `int` should be used wherever previously `long` was used. More consideration has to be applied in interop cases with .NET. - -The Python `int` type in IronPython 3 is implemented as `System.Numerics.BigInteger` (and not as `System.Int32` as it was in IronPython 2). It can contain in theory an arbitrarily large integer (only limited by the 2 GByte memory boundary). - -```pycon ->>> import clr ->>> clr.AddReference("System.Numerics") ->>> import System ->>> int is System.Numerics.BigInteger -True ->>> int is System.Int32 -False ->>> clr.GetClrType(int).Name -'BigInteger' -``` - -This means that in interop cases, when the `int` type is used (think generics), it will mean `BigInteger` and not `Int32` (which was the case in IronPython 2). To retain IronPython 2 semantics, replace `int` with `System.Int32`. - -Example: - -```python -# IronPython 2 -System.Collections.Generic.List[int] -``` - -```python -# IronPython 3 -System.Collections.Generic.List[System.Int32] -``` - -Overview of `int` type equivalency: - -| IronPython 2 | IronPython 3 | .NET | -| ------------ | ------------ | ---------------------------- | -| `long` | `int` | `System.Numerics.BigInteger` | -| `int` | N/A | `System.Int32` | - -### Instances of `int` - -As for instances of `int`, mostly for performance reasons, IronPython may use instances of `System.Int32` to hold smaller integers, while `BigInteger` instances are used for large integers. This is done transparently from the Python side, but again the distinction may become relevant for interop cases. Examples: - -```python -i = 1 # instance of Int32 -j = 1 << 31 # instance of BigInteger -k = j - 1 # still BigInteger, as one of the arguments makes the result type BigInteger -``` - -This means that the type of `Int32` objects is always reported as `int` (which is the same as `BigInteger`). If it is important to check what is the actual type of a given integer object, test if the object is an instance of `System.Int32`. (An alternative way is a test for the presence of `MaxValue` or `MinValue`. For those properties to be visible, `System` has to be imported first.) - -```pycon ->>> import System ->>> type(i) - ->>> isinstance(i, System.Int32) -True ->>> type(j) - ->>> isinstance(j, System.Int32) -False ->>> hex(i.MaxValue) -'0x7fffffff' -``` - -The creation of either `Int32` or `BigInteger` instances happens automatically by the `int` constructor. If for interop purposes it is important to create a `BigInteger` (despite the value fitting in 32 bits), use method `ToBigInteger`. It converts `Int32` values to `BigInteger` and leaves `BigInteger` values unaffected. - -```pycon ->>> bi = i.ToBigInteger() ->>> isinstance(j, System.Int32) -False -``` - -In the opposite direction, if it is essential to create `Int32` objects, either use constructors for `int` or `Int32`. In the current implementation, the former converts an integer to `Int32` if the value fits in 32 bits, otherwise it leaves it as `BigInteger`. The latter throws an exception if the conversion is not possible. Although the behavior of the constructor `int` may or may not change in the future, it is always guaranteed to convert the value to the "canonical form" adopted for that version of IronPython. - -```pycon ->>> # k is a BigInteger that fits in 32 bits ->>> isinstance(k, System.Int32) -False ->>> hex(k) -'0x7fffffff' ->>> ki = int(k) # converts k to Int32 ->>> isinstance(ki, System.Int32) -True ->>> ki = System.Int32(k) # also converts k to Int32 ->>> isinstance(ki, System.Int32) -True ->>> # j is a BigInteger that does not fit in 32 bits ->>> isinstance(j, System.Int32) -False ->>> hex(j) -'0x80000000' ->>> j = int(j) # no type change, j stays BigInteger ->>> isinstance(j, System.Int32) -False ->>> j = System.Int32(j) # conversion fails -Traceback (most recent call last): - File "", line 1, in -OverflowError: Arithmetic operation resulted in an overflow. -``` - -Such explicit conversions are in most cases unnecessary since the runtime recognizes `int`/`Int32` equivalence of instances and performs necessary conversions automatically. - -```pycon ->>> import System ->>> int_list = System.Collections.Generic.List[int]() ->>> int_list.Add(1) # Int32 instance converted to BigInteger ->>> int32_list = System.Collections.Generic.List[System.Int32]() ->>> int32_list.Add((1).ToBigInteger()) # BigInteger instance converted to Int32 ->>> int_list[0] == int32_list[0] -True -``` - -### Pickling and unpickling of `int` - -When an `int` object is serialized using `pickle.dump(x, myfile)` and subsequently unpickled with `x = pickle.load(myfile)` (or `pickle.loads(pickle.dumps(x))`, this has the same effect as reconstructing the object using the `int` constructor, i.e. `x = int(x)`. In other words, if the `x` instance was `BigInteger` but the value fits in `Int32`, it will be reconstructed as `Int32`. - -### BigIntegerV2 API - -In IronPython 2, `long` type carries an obsolete `BigIntegerV2` API, accessible after importing `System`. In IronPython 3 this API is not available directly on `int` instances (regardless of whether the instance is `Int32` or `BigInteger`), but is still accessible in some form through `Microsoft.Scripting.Utils.MathUtils` in `Microsoft.Dynamic.dll`. - -```pycon ->>> # IronPython 2 ->>> i = 1 # instance of Int32 (int) ->>> j = 1 << 64 # instance of BigInteger (long) ->>> import System ->>> j.GetWords() -Array[UInt32]((0, 0, 1)) ->>> i.GetWords() -Traceback (most recent call last): - File "", line 1, in -AttributeError: 'int' object has no attribute 'GetWords' ->>> long.GetWords(i) -Array[UInt32]((1)) -``` - -```pycon ->>> # IronPython 3 ->>> i = 1 # instance of Int32 (int) ->>> j = 1 << 64 # instance of BigInteger (int) ->>> import clr ->>> clr.AddReference("Microsoft.Dynamic") ->>> import Microsoft.Scripting.Utils.MathUtils ->>> clr.ImportExtensions(Microsoft.Scripting.Utils.MathUtils) ->>> j.GetWords() -Array[UInt32]((0, 0, 1)) ->>> i.GetWords() -Traceback (most recent call last): - File "", line 1, in -AttributeError: 'int' object has no attribute 'GetWords' ->>> Microsoft.Scripting.Utils.MathUtils.GetWords(i) -Array[UInt32]((1)) -``` - -Another set of Python-hidden methods on `long` in IronPython 2 that are not available on `int` in IronPython 3 are conversion methods with names like `ToXxx`. The recommended way to perform type conversions like those is to use type constructors. The exception is the conversion to `BigInteger` itself, for the reasons explained above. - -```python -# IronPython 2 -j = long(1) -i64 = j.ToInt64() -``` - -```python -# IronPython 3 -import System -j = (1).ToBigInteger() -i64 = System.Int64(j) -``` - -### `range` - -IronPython's `range` is a generator that produces a sequence of `int` values. The values are instances of `Int32` or `BigInteger`, depending on the actual integer value they represent. When `range` is used in a LINQ context, it exposes interface `IEnumerable` and all values generated are of type `Int32`. This limits the possible value to the range `Int32.MinValue` to `Int32.MaxValue`. - -[PEP 0237]: https://python.org/dev/peps/pep-0237 - From 9830c7788f4e7b38a8e51275b59ca5b6e0113d89 Mon Sep 17 00:00:00 2001 From: Lamparter Date: Sun, 17 Nov 2024 14:19:17 +0000 Subject: [PATCH 06/26] Move images --- Documentation/logo.png => .github/PackageLogo.png | Bin Documentation/logo.svg => .github/PackageLogo.svg | 0 2 files changed, 0 insertions(+), 0 deletions(-) rename Documentation/logo.png => .github/PackageLogo.png (100%) rename Documentation/logo.svg => .github/PackageLogo.svg (100%) diff --git a/Documentation/logo.png b/.github/PackageLogo.png similarity index 100% rename from Documentation/logo.png rename to .github/PackageLogo.png diff --git a/Documentation/logo.svg b/.github/PackageLogo.svg similarity index 100% rename from Documentation/logo.svg rename to .github/PackageLogo.svg From b187b7b5f20ad1da18b280bf5f3c99ad5cca7345 Mon Sep 17 00:00:00 2001 From: Lamparter Date: Sun, 17 Nov 2024 14:29:59 +0000 Subject: [PATCH 07/26] Fix references --- Package/dotnettool/IronPython.Console.csproj | 6 +++--- Package/nuget/IronPython.StdLib.nuspec | 4 ++-- Package/nuget/IronPython.nuspec | 4 ++-- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/Package/dotnettool/IronPython.Console.csproj b/Package/dotnettool/IronPython.Console.csproj index 9fb8878c3..4b23bbe31 100644 --- a/Package/dotnettool/IronPython.Console.csproj +++ b/Package/dotnettool/IronPython.Console.csproj @@ -34,7 +34,7 @@ This package contains a standalone Python interpreter, invokable from the command line as ipy. It also includes the Python Standard Library released by the Python project, but slightly modified to work better with IronPython and .NET. ironpython python dynamic dlr README.md - logo.png + PackageLogo.png @@ -55,8 +55,8 @@ This package contains a standalone Python interpreter, invokable from the comman - - + + diff --git a/Package/nuget/IronPython.StdLib.nuspec b/Package/nuget/IronPython.StdLib.nuspec index f62df7e74..7577cd1e1 100644 --- a/Package/nuget/IronPython.StdLib.nuspec +++ b/Package/nuget/IronPython.StdLib.nuspec @@ -10,7 +10,7 @@ StdLib.License.txt false The Python Standard Library, for use with IronPython. - logo.png + PackageLogo.png en-US ironpython python dynamic dlr standard library @@ -24,6 +24,6 @@ - + diff --git a/Package/nuget/IronPython.nuspec b/Package/nuget/IronPython.nuspec index 8711f555a..2404a3742 100644 --- a/Package/nuget/IronPython.nuspec +++ b/Package/nuget/IronPython.nuspec @@ -14,7 +14,7 @@ This package contains the IronPython interpreter engine. README.md - logo.png + PackageLogo.png en-US ironpython python dynamic dlr @@ -45,6 +45,6 @@ This package contains the IronPython interpreter engine. - + From 0141a4524a04ad3e93210d739e657d5ddd5fd3e1 Mon Sep 17 00:00:00 2001 From: Lamparter Date: Sun, 17 Nov 2024 14:34:11 +0000 Subject: [PATCH 08/26] Fix documentation references --- .github/README.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/.github/README.md b/.github/README.md index 6d53eb37c..659e45af9 100644 --- a/.github/README.md +++ b/.github/README.md @@ -59,31 +59,31 @@ The current target is Python 3.4, although features and behaviors from later ver See the following lists for features from each version of CPython that have been implemented: -- [What's New In Python 3.0](WhatsNewInPython30.md) -- [What's New In Python 3.1](WhatsNewInPython31.md) -- [What's New In Python 3.2](WhatsNewInPython32.md) -- [What's New In Python 3.3](WhatsNewInPython33.md) -- [What's New In Python 3.4](WhatsNewInPython34.md) -- [What's New In Python 3.5](WhatsNewInPython35.md) -- [What's New In Python 3.6](WhatsNewInPython36.md) +- [`Python3.0`](https://github.com/IronLanguages/ironpython3/wiki/WhatsNew%E2%80%90Python3.0) +- [`Python3.1`](https://github.com/IronLanguages/ironpython3/wiki/WhatsNew%E2%80%90Python3.1) +- [`Python3.2`](https://github.com/IronLanguages/ironpython3/wiki/WhatsNew%E2%80%90Python3.2) +- [`Python3.3`](https://github.com/IronLanguages/ironpython3/wiki/WhatsNew%E2%80%90Python3.3) +- [`Python3.4`](https://github.com/IronLanguages/ironpython3/wiki/WhatsNew%E2%80%90Python3.4) +- [`Python3.5`](https://github.com/IronLanguages/ironpython3/wiki/WhatsNew%E2%80%90Python3.5) +- [`Python3.6`](https://github.com/IronLanguages/ironpython3/wiki/WhatsNew%E2%80%90Python3.6) ## Contributing For details on contributing see the [Contributing](CONTRIBUTING.md) article. ## Upgrading from IronPython 2 -For details on upgrading from IronPython 2 to 3 see the [Upgrading from IronPython 2 to 3](Documentation/upgrading-from-ipy2.md) article. +For details on upgrading from IronPython 2 to 3 see the [Upgrading from IronPython 2 to 3](https://github.com/IronLanguages/ironpython3/wiki/Upgrading-from-IronPython2) article. ## Differences with CPython -While compatibility with CPython is one of our main goals with IronPython 3, there are still some differences that may cause issues. See [Differences from CPython](Documentation/differences-from-c-python.md) for details. +While compatibility with CPython is one of our main goals with IronPython 3, there are still some differences that may cause issues. See [Differences from CPython](https://github.com/IronLanguages/ironpython3/wiki/Differences-from-CPython) for details. ## Package compatibility -See the [Package compatibility](Documentation/package-compatibility.md) document for information on compatibility with popular packages. +See the [Package compatibility](https://github.com/IronLanguages/ironpython3/wiki/Package-compatibility) document for information on compatibility with popular packages. ## Installation -Binaries of IronPython 3 can be downloaded from the [release page](https://github.com/IronLanguages/ironpython3/releases/latest), available in various formats: `.msi`, `.zip`, `.deb`, `.pkg`. The IronPython package is also available on [NuGet](https://www.nuget.org/packages/IronPython/3.4.0). See the [installation document](Documentation/installing.md) for detailed instructions on how to install a standalone IronPython interpreter on various operating systems and .NET frameworks. +Binaries of IronPython 3 can be downloaded from the [release page](https://github.com/IronLanguages/ironpython3/releases/latest), available in various formats: `.msi`, `.zip`, `.deb`, `.pkg`. The IronPython package is also available on [NuGet](https://www.nuget.org/packages/IronPython/3.4.0). See the [installation document](https://github.com/IronLanguages/ironpython3/wiki/Installing) for detailed instructions on how to install a standalone IronPython interpreter on various operating systems and .NET frameworks. ## Build -See the [building document](Documentation/building.md). Since the main development is on Windows, bugs on other platforms may inadvertently be introduced - please report them! +See the [building document](https://github.com/IronLanguages/ironpython3/wiki/Building). Since the main development is on Windows, bugs on other platforms may inadvertently be introduced - please report them! ## Supported Platforms IronPython 3 targets .NET Framework 4.6.2, .NET Standard 2.0 and .NET 6.0. The support for .NET and .NET Core follow the lifecycle defined on [.NET and .NET Core Support Policy](https://dotnet.microsoft.com/platform/support/policy/dotnet-core). From 35d0f65a9f9ab2ea0b569250fd8cf1268381864c Mon Sep 17 00:00:00 2001 From: Lamparter Date: Sun, 17 Nov 2024 14:42:39 +0000 Subject: [PATCH 09/26] Improve `README.md` --- .github/README.md | 55 +++++++++++++++++++++++++++-------------------- 1 file changed, 32 insertions(+), 23 deletions(-) diff --git a/.github/README.md b/.github/README.md index 659e45af9..6576885c2 100644 --- a/.github/README.md +++ b/.github/README.md @@ -1,22 +1,29 @@ -IronPython 3 -============ -**There is still much that needs to be done to support Python 3.x. We are working on it, albeit slowly. We welcome all those who would like to help!** - -[Official Website](https://ironpython.net) +

+ IronPython Console +

+ +

+ + IronPython Website + + GitHub CI Status + + Azure CI Status + + Gitter +

+ +**IronPython** is a popular, open-source implementation of Python 3.x for .NET that is built on top of its very own [Dynamic Language Runtime](https://github.com/IronLanguages/dlr). + +> [!NOTE] +> There is still much that needs to be done to support Python 3. We are working on it, albeit slowly. +> We welcome all those who would like to help! ❤️ IronPython is an open-source implementation of the Python programming language that is tightly integrated with .NET. IronPython can use .NET and Python libraries, and other .NET languages can use Python code just as easily. IronPython 3 targets Python 3, including the re-organized standard library, Unicode strings, and all of the other new features. - -| **What?** | **Where?** | -| --------: | :------------: | -| **Windows/Linux/macOS Builds** | [![Build status](https://dotnet.visualstudio.com/IronLanguages/_apis/build/status/ironpython3)](https://dotnet.visualstudio.com/IronLanguages/_build/latest?definitionId=43) [![Github build status](https://github.com/IronLanguages/ironpython3/workflows/CI/badge.svg)](https://github.com/IronLanguages/ironpython3/actions?workflow=CI) | -| **Downloads** | [![NuGet](https://img.shields.io/nuget/vpre/IronPython.svg)](https://www.nuget.org/packages/IronPython/3.4.0) [![Release](https://img.shields.io/github/release/IronLanguages/ironpython3.svg?include_prereleases)](https://github.com/IronLanguages/ironpython3/releases/latest)| -| **Help** | [![Gitter chat](https://badges.gitter.im/IronLanguages/ironpython.svg)](https://gitter.im/IronLanguages/ironpython) [![StackExchange](https://img.shields.io/badge/stack%20overflow-ironpython-informational?logo=stack-overflow&logoColor=white)](https://stackoverflow.com/questions/tagged/ironpython) | - - -## Examples +## ✍️ Examples The following C# program: @@ -48,13 +55,15 @@ def greetings(name): dynamic greetings = scope.GetVariable("greetings"); System.Console.WriteLine(greetings("world")); ``` -This example assumes that `IronPython` has been added to the C# project as a NuGet package. -## Code of Conduct +> This example assumes that `IronPython` has been added to the C# project as a NuGet package. + +## ⚖️ Code of Conduct This project has adopted the code of conduct defined by the Contributor Covenant to clarify expected behavior in our community. For more information see the [.NET Foundation Code of Conduct](https://dotnetfoundation.org/code-of-conduct). -## State of the Project +## 🐍 State of the Project + The current target is Python 3.4, although features and behaviors from later versions may be included. See the following lists for features from each version of CPython that have been implemented: @@ -67,22 +76,22 @@ See the following lists for features from each version of CPython that have been - [`Python3.5`](https://github.com/IronLanguages/ironpython3/wiki/WhatsNew%E2%80%90Python3.5) - [`Python3.6`](https://github.com/IronLanguages/ironpython3/wiki/WhatsNew%E2%80%90Python3.6) -## Contributing +## 🙋 Contributing For details on contributing see the [Contributing](CONTRIBUTING.md) article. -## Upgrading from IronPython 2 +## ⬆️ Upgrading from IronPython 2 For details on upgrading from IronPython 2 to 3 see the [Upgrading from IronPython 2 to 3](https://github.com/IronLanguages/ironpython3/wiki/Upgrading-from-IronPython2) article. -## Differences with CPython +## 🧭 Differences with CPython While compatibility with CPython is one of our main goals with IronPython 3, there are still some differences that may cause issues. See [Differences from CPython](https://github.com/IronLanguages/ironpython3/wiki/Differences-from-CPython) for details. -## Package compatibility +## 📦 Package compatibility See the [Package compatibility](https://github.com/IronLanguages/ironpython3/wiki/Package-compatibility) document for information on compatibility with popular packages. -## Installation +## 🎁 Installation Binaries of IronPython 3 can be downloaded from the [release page](https://github.com/IronLanguages/ironpython3/releases/latest), available in various formats: `.msi`, `.zip`, `.deb`, `.pkg`. The IronPython package is also available on [NuGet](https://www.nuget.org/packages/IronPython/3.4.0). See the [installation document](https://github.com/IronLanguages/ironpython3/wiki/Installing) for detailed instructions on how to install a standalone IronPython interpreter on various operating systems and .NET frameworks. -## Build +## 🛠️ Build See the [building document](https://github.com/IronLanguages/ironpython3/wiki/Building). Since the main development is on Windows, bugs on other platforms may inadvertently be introduced - please report them! ## Supported Platforms From e43cf2dd1b735330bba6045d3ac553b887f3e855 Mon Sep 17 00:00:00 2001 From: Lamparter Date: Sun, 17 Nov 2024 14:48:55 +0000 Subject: [PATCH 10/26] Improve sections in `README.md` --- .github/README.md | 35 ++++++++++++++++++----------------- 1 file changed, 18 insertions(+), 17 deletions(-) diff --git a/.github/README.md b/.github/README.md index 6576885c2..76267dda1 100644 --- a/.github/README.md +++ b/.github/README.md @@ -23,6 +23,10 @@ IronPython is an open-source implementation of the Python programming language t IronPython 3 targets Python 3, including the re-organized standard library, Unicode strings, and all of the other new features. +## 🎁 Installation + +Binaries of IronPython 3 can be downloaded from the [release page](https://github.com/IronLanguages/ironpython3/releases/latest), available in various formats: `.msi`, `.zip`, `.deb`, `.pkg`. The IronPython package is also available on [NuGet](https://www.nuget.org/packages/IronPython). See the [installation article](https://github.com/IronLanguages/ironpython3/wiki/Installing) for detailed instructions on how to install a standalone IronPython interpreter on various operating systems and .NET frameworks. + ## ✍️ Examples The following C# program: @@ -58,10 +62,6 @@ System.Console.WriteLine(greetings("world")); > This example assumes that `IronPython` has been added to the C# project as a NuGet package. -## ⚖️ Code of Conduct -This project has adopted the code of conduct defined by the Contributor Covenant to clarify expected behavior in our community. -For more information see the [.NET Foundation Code of Conduct](https://dotnetfoundation.org/code-of-conduct). - ## 🐍 State of the Project The current target is Python 3.4, although features and behaviors from later versions may be included. @@ -77,22 +77,23 @@ See the following lists for features from each version of CPython that have been - [`Python3.6`](https://github.com/IronLanguages/ironpython3/wiki/WhatsNew%E2%80%90Python3.6) ## 🙋 Contributing -For details on contributing see the [Contributing](CONTRIBUTING.md) article. -## ⬆️ Upgrading from IronPython 2 -For details on upgrading from IronPython 2 to 3 see the [Upgrading from IronPython 2 to 3](https://github.com/IronLanguages/ironpython3/wiki/Upgrading-from-IronPython2) article. +Want to contribute to this project? Let us know with an [issue](https://github.com/IronLanguages/IronPython3/issues) that communicates your intent to create a [pull request](https://github.com/IronLanguages/IronPython3/pulls). Also, view our [contributing guidelines](CONTRIBUTING.md) to make sure you're up to date on the coding conventions. +For more details on contributing see the [Contributing](CONTRIBUTING.md) article. -## 🧭 Differences with CPython -While compatibility with CPython is one of our main goals with IronPython 3, there are still some differences that may cause issues. See [Differences from CPython](https://github.com/IronLanguages/ironpython3/wiki/Differences-from-CPython) for details. +#### 🫡 Code of Conduct +This project has adopted the code of conduct defined by the Contributor Covenant to clarify expected behavior in our community. +For more information see the [.NET Foundation Code of Conduct](https://dotnetfoundation.org/code-of-conduct). -## 📦 Package compatibility -See the [Package compatibility](https://github.com/IronLanguages/ironpython3/wiki/Package-compatibility) document for information on compatibility with popular packages. +### 🛠️ Building from source -## 🎁 Installation -Binaries of IronPython 3 can be downloaded from the [release page](https://github.com/IronLanguages/ironpython3/releases/latest), available in various formats: `.msi`, `.zip`, `.deb`, `.pkg`. The IronPython package is also available on [NuGet](https://www.nuget.org/packages/IronPython/3.4.0). See the [installation document](https://github.com/IronLanguages/ironpython3/wiki/Installing) for detailed instructions on how to install a standalone IronPython interpreter on various operating systems and .NET frameworks. +See the article on [building from source](https://github.com/IronLanguages/ironpython3/wiki/Building). Since the main development is on Windows, bugs on other platforms may inadvertently be introduced - please report them! + +### ⚖️ License + +This project is licensed under the Apache-2.0 License as stated in the [`LICENSE`](https://github.com/IronLanguages/ironpython3/blob/56d1799/LICENSE). +> Copyright (c) .NET Foundation and Contributors. -## 🛠️ Build -See the [building document](https://github.com/IronLanguages/ironpython3/wiki/Building). Since the main development is on Windows, bugs on other platforms may inadvertently be introduced - please report them! +### 📝 Wiki -## Supported Platforms -IronPython 3 targets .NET Framework 4.6.2, .NET Standard 2.0 and .NET 6.0. The support for .NET and .NET Core follow the lifecycle defined on [.NET and .NET Core Support Policy](https://dotnet.microsoft.com/platform/support/policy/dotnet-core). +The documentation and guides for IronPython are available [on the wiki](https://github.com/IronLanguages/ironpython3/wiki). Enjoy! From e0800724b34bae5b7a88a73b5934b68899e4df0b Mon Sep 17 00:00:00 2001 From: Lamparter Date: Sun, 17 Nov 2024 14:51:36 +0000 Subject: [PATCH 11/26] Ignore languages from GitHub Linguist --- .gitattributes | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/.gitattributes b/.gitattributes index 5c5441dd2..4f2a2e1cf 100644 --- a/.gitattributes +++ b/.gitattributes @@ -44,3 +44,11 @@ Tests/file_without_BOM.txt -text # Do not normalize on commit. *.pdf -text + +# Ignore languages from GitHub Linguist +*.1 linguist-detectable=false +*.2 linguist-detectable=false +*.3 linguist-detectable=false +*.html linguist-detectable=false +*.pck linguist-detectable=false +*.ps1 linguist-detectable=false From d7364b779558692b557b866e870fb1c6ba3bc56f Mon Sep 17 00:00:00 2001 From: Lamparter Date: Sun, 17 Nov 2024 15:10:07 +0000 Subject: [PATCH 12/26] Fix references in solution --- IronPython.sln | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/IronPython.sln b/IronPython.sln index 3de1c02d7..2f9cbaa42 100644 --- a/IronPython.sln +++ b/IronPython.sln @@ -23,10 +23,10 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Solution Items", "Solution CurrentVersion.props = CurrentVersion.props Directory.Build.props = Directory.Build.props IronPython.ruleset = IronPython.ruleset - LICENSE = LICENSE + LICENSE.md = LICENSE.md make.ps1 = make.ps1 NuGet.config = NuGet.config - README.md = README.md + .github\README.md = .github\README.md EndProjectSection EndProject Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "IronPython.SQLite", "Src\IronPython.SQLite\IronPython.SQLite.csproj", "{4A617A40-2BA7-4713-AAFE-F90C4325C581}" From ccad23347c7b3ddf86328f0315b6aa3da99eb385 Mon Sep 17 00:00:00 2001 From: Lamparter Date: Sun, 17 Nov 2024 15:12:39 +0000 Subject: [PATCH 13/26] Add bug report issue template --- .github/ISSUE_TEMPLATE/bug_report.yml | 72 +++++++++++++++++++++++++++ 1 file changed, 72 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.yml diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 000000000..bd1cb0434 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,72 @@ +name: Bug Report +description: Create a bug report to help improve! +labels: [bug] +title: "Bug: " +type: Bug +body: + - type: markdown + attributes: + value: | + ##### ⏱️ Before you start... + - Are you on the latest version? You might be using an old version. + - Have you checked whether or not a similar bug has already been reported? + - type: textarea + attributes: + label: 🪟 What OS build is this issue present? + description: Windows key + R > winver.exe / Apple Logo (in menu bar) > About This Mac (may not be like this on Ventura) + placeholder: Windows 11 Insider Beta 22623.1250 / macOS Monterey 12.6.3 + - type: textarea + attributes: + label: 🔢 What version are you on? + - type: textarea + attributes: + label: 📄 Description + description: A clear and concise description of what the bug is. + validations: + required: true + - type: textarea + attributes: + label: 🪜 Steps To Reproduce + description: Steps to reproduce the behavior. + placeholder: | + 1. Go to '....' + 2. Click on '....' + 3. Scroll down to '....' + 4. See the error + validations: + required: false + - type: textarea + attributes: + label: 🤔 Expected behavior + description: A clear and concise description of what you expected to happen. + - type: dropdown + id: platforms-affected + attributes: + label: Affected platforms + description: Select all or any platform that you see this issue on. This helps us determine if it's something platform-specific or in the core. If you were only able to test on 1 platform, please check the last option to inform us about that. + multiple: true + options: + - 📱 Android + - 📲 iOS + - 💻 macOS + - 🪨 Rosetta (macOS Catalyst) + - 🪟 Windows + - 🪟 WPF + - 🐧 GTK + - 🐧 Linux Framebuffer + - ⌨️ Skia Desktop + - 🕸️ WebAssembly + - ❓ Other + - ☹️ I was unable to test on other platforms + validations: + required: true + - type: textarea + id: workaround + attributes: + label: ⚒️ Did you find any workaround? + description: Did you find any workaround for this issue? This can unblock other people while waiting for this issue to be resolved or even give us a hint on how to fix this. + - type: textarea + attributes: + label: 📸 Assets + description: | + A list of assets (errors, screenshots) relevant to the bug. From fa337a56755c530339e3196855a77c1a75827bb2 Mon Sep 17 00:00:00 2001 From: Lamparter Date: Sun, 17 Nov 2024 15:13:57 +0000 Subject: [PATCH 14/26] Add feature request issue template --- .github/ISSUE_TEMPLATE/feature_request.yml | 67 ++++++++++++++++++++++ 1 file changed, 67 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/feature_request.yml diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 000000000..2ad820872 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,67 @@ +name: Feature Request +description: Request a new feature to make things better! +labels: [feature request] +title: "Feature: " +type: Feature +body: + - type: markdown + attributes: + value: | + ##### ⏱️ Before you start... + - Have you checked whether or not a similar feature request has already been reported? + - type: textarea + attributes: + label: 📄 Description + description: A clear and concise description of what your idea is. Include things like possible use cases, drawbacks, etc. + validations: + required: true + - type: textarea + attributes: + label: 🗃️ Alternative solutions + description: Describe more ways this idea could be implemented. + validations: + required: false + - type: textarea + id: api-changes + attributes: + label: ⚡ API Changes + description: Include a list of all API changes, additions, subtractions as would be required by your proposal. These APIs should be considered placeholders, so the naming is not as important as getting the concepts correct. If possible you should include some example (pseudo-)code of usage of your new API. + placeholder: | + ```csharp + var button = new Button (); + button.MakeShiny = true; // new API + ``` + + The MakeShiny API works even if the button is already visible. + validations: + required: false + - type: textarea + id: use-case + attributes: + label: 👥 Intended Use-Case + description: Provide a detailed example of where your proposal would be used and for what purpose. Focus on _why_ you want this feature instead of _what_ the feature does. + placeholder: I have a situation where I would really want a shiny button to make it stand out from the rest of the plain and boring buttons. + validations: + required: false + - type: textarea + attributes: + label: ✅ Tasks + description: Give an overview of all the specific things you would like to be changed or implemented. + value: | + #### 📋 High Priority + - [ ] Something + - [ ] Another thing + - [ ] https://github.com/link/to/an/issue + + #### 📋 Nice to have + - [ ] Something + - [ ] Another thing + - [ ] https://github.com/link/to/an/issue + validations: + required: false + - type: textarea + attributes: + label: 📸 Assets + description: A list of assets (screenshots, mockups) relevant to this feature request. + validations: + required: false From d16281781df91e08ce181c43988b54b689188da2 Mon Sep 17 00:00:00 2001 From: Lamparter Date: Sun, 17 Nov 2024 15:14:24 +0000 Subject: [PATCH 15/26] Add spec issue template --- .github/ISSUE_TEMPLATE/spec.yml | 74 +++++++++++++++++++++++++++++++++ 1 file changed, 74 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/spec.yml diff --git a/.github/ISSUE_TEMPLATE/spec.yml b/.github/ISSUE_TEMPLATE/spec.yml new file mode 100644 index 000000000..b2a3c4923 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/spec.yml @@ -0,0 +1,74 @@ +name: Spec +description: An official specification for enhancements. +labels: ["enhancement"] +assignees: [] +title: "Spec: " +type: Spec +body: + - type: markdown + attributes: + value: | + Thank you for taking the time to provide us with a detailed specification of your idea. + + In a spec you will give a detailed and complete representation of the (public) APIs that are implemented as part of this change. Additionally please think about backwards compatibility, breaking changes, supported platforms and the difficulty. + - type: textarea + id: description + attributes: + label: 📄 Description + description: Provide a concise description of the feature and the motivation for adding it. This can be a modified version from the feature request prior to this. + validations: + required: true + - type: textarea + id: api-changes + attributes: + label: ⚡ API Changes + description: Include a complete list of all API changes, additions, subtractions as would be required by your proposal. + value: | + ## `[ class ]` + + | API | Description | + | ------------- | ------------- | + | [name] | Gets or sets [description]. | + validations: + required: true + - type: textarea + id: usage-scenarios + attributes: + label: 👥 Usage scenarios + description: Give us a couple of scenarios that demonstrate how developers would consume the above APIs. + placeholder: | + # C# Example + ```csharp + var thing = new MyNewControl(); + thing.BeAwesome = true; + thing.Color = Colors.Cornsilk; + ``` + + # XAML Example + ```xaml + + ``` + validations: + required: true + - type: textarea + id: backwards-compatibility + attributes: + label: 🔙 Backward Compatibility + description: Please describe here anything in terms of backwards compatibility. Will there be breaking changes? Do we need to update dependencies to support this? What are the minimum supported API/OS levels? And lastly, are there any platforms that can't support this and why? + placeholder: | + Minimum API levels? + Breaking changes? + Unsupported platforms? + validations: + required: false + - type: dropdown + id: difficulty + attributes: + label: 🤔 Difficulty + description: What do you feel will be the difficulty of this change all things considering? No exact science, just your gut feeling. + options: + - Low + - Medium + - High + validations: + required: true From c7961d19b35f53fc090f8aff029ce662308e779c Mon Sep 17 00:00:00 2001 From: Lamparter Date: Sun, 17 Nov 2024 15:17:46 +0000 Subject: [PATCH 16/26] Create issue template config --- .github/ISSUE_TEMPLATE/config.yml | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/config.yml diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 000000000..302cd1605 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,5 @@ +blank_issues_enabled: false +contact_links: + - name: Discussion + url: https://github.com/IronLanguages/ironpython3/discussions + about: "Ask questions, discuss implementation, or just have a chat! If you're unsure what to choose, a discussion is probably best." From aba3b0e51d2c0f96664f83464358144a3c4d9c50 Mon Sep 17 00:00:00 2001 From: Lamparter Date: Sun, 17 Nov 2024 15:19:56 +0000 Subject: [PATCH 17/26] Add PR template --- .github/pull_request_template.md | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) create mode 100644 .github/pull_request_template.md diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 000000000..606a40405 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,28 @@ + + +### 📄 Description + + + +### 🗃️ Alternative solutions + + + +### ✅ Tasks + + +#### 📋 High Priority +- [ ] Something +- [ ] Another thing +- [ ] https://github.com/link/to/an/issue + +#### 📋 Nice to have +- [ ] Something +- [ ] Another thing +- [ ] https://github.com/link/to/an/issue + +### 📸 Assets + From f16e79cfb1f8c086416465b22bf691b989e03080 Mon Sep 17 00:00:00 2001 From: Lamparter Date: Mon, 18 Nov 2024 07:57:07 +0000 Subject: [PATCH 18/26] Add link to "Using IronPython" wiki under examples section in `README.md` --- .github/README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/README.md b/.github/README.md index 76267dda1..35d0cefbd 100644 --- a/.github/README.md +++ b/.github/README.md @@ -62,6 +62,8 @@ System.Console.WriteLine(greetings("world")); > This example assumes that `IronPython` has been added to the C# project as a NuGet package. +More examples and documentation on how to use IronPython outside the interactive console can be found [here](https://github.com/IronLanguages/ironpython3/wiki/Using-IronPython). + ## 🐍 State of the Project The current target is Python 3.4, although features and behaviors from later versions may be included. From d0bee731916c2a950a4c5a7ad9e9583ae0512750 Mon Sep 17 00:00:00 2001 From: Lamparter Date: Mon, 18 Nov 2024 16:07:37 +0000 Subject: [PATCH 19/26] Force allow blank issues --- .github/ISSUE_TEMPLATE/config.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index 302cd1605..aa9217e83 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -1,4 +1,4 @@ -blank_issues_enabled: false +blank_issues_enabled: true contact_links: - name: Discussion url: https://github.com/IronLanguages/ironpython3/discussions From b49e6c3d758b5e082356e4aa6f031cfd694112d3 Mon Sep 17 00:00:00 2001 From: Lamparter Date: Mon, 18 Nov 2024 16:25:33 +0000 Subject: [PATCH 20/26] Improve bug report template --- .github/ISSUE_TEMPLATE/bug_report.yml | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index bd1cb0434..7bbe3a928 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -18,6 +18,23 @@ body: - type: textarea attributes: label: 🔢 What version are you on? + placeholder: '3.4.1 (3.4.1.1000) [.NETFramework,Version=v4.6.2 on .NET Framework 4.8.9282.0 (64-bit)]' + description: If you are using the console program, provide the value of `sys.version`. If it is a local build, provide also the git hash of the commit used to build IronPython. If you are using IronPython embedded inside a .NET app, provide the version of the NuGet package you installed. + validations: + required: true + - type: dropdown + attributes: + label: 📦 What .NET platform did you use? + multiple: false + options: + - .NET + - .NET Core + - .NET Framework + - Mono + - Unity + - Xamarin + validations: + required: true - type: textarea attributes: label: 📄 Description From 48e1d17806ff7bd05373d67b10a7db2cc51b5a78 Mon Sep 17 00:00:00 2001 From: Lamparter Date: Mon, 18 Nov 2024 16:25:51 +0000 Subject: [PATCH 21/26] Remove `type` from bug report --- .github/ISSUE_TEMPLATE/bug_report.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index 7bbe3a928..2013a9dc5 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -2,7 +2,7 @@ name: Bug Report description: Create a bug report to help improve! labels: [bug] title: "Bug: " -type: Bug +# type: Bug body: - type: markdown attributes: From 61ea588cc16cbaf18bfbdd190bbd1ca64a5d6052 Mon Sep 17 00:00:00 2001 From: Lamparter Date: Mon, 18 Nov 2024 16:26:07 +0000 Subject: [PATCH 22/26] Remove `type` from feature request --- .github/ISSUE_TEMPLATE/feature_request.yml | 1 - 1 file changed, 1 deletion(-) diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml index 2ad820872..f5377a3f5 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.yml +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -2,7 +2,6 @@ name: Feature Request description: Request a new feature to make things better! labels: [feature request] title: "Feature: " -type: Feature body: - type: markdown attributes: From 02dad37eae13c5e6a50f94899195dae336e930bb Mon Sep 17 00:00:00 2001 From: Lamparter Date: Mon, 18 Nov 2024 16:26:27 +0000 Subject: [PATCH 23/26] Remove `type` from spec issue --- .github/ISSUE_TEMPLATE/spec.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/ISSUE_TEMPLATE/spec.yml b/.github/ISSUE_TEMPLATE/spec.yml index b2a3c4923..01554c08d 100644 --- a/.github/ISSUE_TEMPLATE/spec.yml +++ b/.github/ISSUE_TEMPLATE/spec.yml @@ -3,7 +3,7 @@ description: An official specification for enhancements. labels: ["enhancement"] assignees: [] title: "Spec: " -type: Spec +# type: Spec body: - type: markdown attributes: From 2583c6c442f63282a0705b8e65ee3c3e5428a830 Mon Sep 17 00:00:00 2001 From: Lamparter Date: Mon, 18 Nov 2024 16:26:48 +0000 Subject: [PATCH 24/26] Add comment --- .github/ISSUE_TEMPLATE/feature_request.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml index f5377a3f5..b7210aec7 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.yml +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -2,6 +2,7 @@ name: Feature Request description: Request a new feature to make things better! labels: [feature request] title: "Feature: " +# type: Feature body: - type: markdown attributes: From 56c0e14730f845a789d15513be1fffc9622ddc29 Mon Sep 17 00:00:00 2001 From: Lamparter Date: Mon, 18 Nov 2024 19:01:05 +0000 Subject: [PATCH 25/26] Fix MSBuild references --- Build.proj | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Build.proj b/Build.proj index 21c6967d6..1c6bc9d86 100644 --- a/Build.proj +++ b/Build.proj @@ -44,8 +44,8 @@ - - + + From 57e5905b417a37badb7a46925fb68a5b79df2e54 Mon Sep 17 00:00:00 2001 From: Lamparter Date: Mon, 18 Nov 2024 19:06:34 +0000 Subject: [PATCH 26/26] Replace Unicode dash with ASCII dash in "what's new" wiki pages --- .github/README.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/.github/README.md b/.github/README.md index 35d0cefbd..d372fa154 100644 --- a/.github/README.md +++ b/.github/README.md @@ -70,13 +70,13 @@ The current target is Python 3.4, although features and behaviors from later ver See the following lists for features from each version of CPython that have been implemented: -- [`Python3.0`](https://github.com/IronLanguages/ironpython3/wiki/WhatsNew%E2%80%90Python3.0) -- [`Python3.1`](https://github.com/IronLanguages/ironpython3/wiki/WhatsNew%E2%80%90Python3.1) -- [`Python3.2`](https://github.com/IronLanguages/ironpython3/wiki/WhatsNew%E2%80%90Python3.2) -- [`Python3.3`](https://github.com/IronLanguages/ironpython3/wiki/WhatsNew%E2%80%90Python3.3) -- [`Python3.4`](https://github.com/IronLanguages/ironpython3/wiki/WhatsNew%E2%80%90Python3.4) -- [`Python3.5`](https://github.com/IronLanguages/ironpython3/wiki/WhatsNew%E2%80%90Python3.5) -- [`Python3.6`](https://github.com/IronLanguages/ironpython3/wiki/WhatsNew%E2%80%90Python3.6) +- [`Python3.0`](https://github.com/IronLanguages/ironpython3/wiki/WhatsNew–Python3.0) +- [`Python3.1`](https://github.com/IronLanguages/ironpython3/wiki/WhatsNew–Python3.1) +- [`Python3.2`](https://github.com/IronLanguages/ironpython3/wiki/WhatsNew–Python3.2) +- [`Python3.3`](https://github.com/IronLanguages/ironpython3/wiki/WhatsNew–Python3.3) +- [`Python3.4`](https://github.com/IronLanguages/ironpython3/wiki/WhatsNew–Python3.4) +- [`Python3.5`](https://github.com/IronLanguages/ironpython3/wiki/WhatsNew–Python3.5) +- [`Python3.6`](https://github.com/IronLanguages/ironpython3/wiki/WhatsNew–Python3.6) ## 🙋 Contributing