عرض مصدر Python/itertools/permutations

<noinclude>{{DISPLAYTITLE:الدالة <code>itertools.permutations()‎</code> في بايثون}}</noinclude>
تعيد الدّالة <code>itertools.permutations()‎</code> تبادلات مُتتابعةً بطول مُعيّن من عناصر الكائن القابل للتّكرار المُعطى.

تُنتَج التّبادلات حسب الترتيب المُعجميّ (lexicographic). ما يعني بأنّ الصّفوف النّاتجة ستكون مُرتّبةً إن كان الكائن القابل للتّكرار المُعطى مُرتّبًا.

تُعامَل العناصر على أنّها فريدة حسب موقعها، وليس حسب قيمها. لذا إن كانت عناصر الكائن القابل للتّكرار المُدخَل فريدةً فلن تُكرّر أيّة قيم في كلّ تبادل.

== البنية العامة ==
<syntaxhighlight lang="python3">
itertools.permutations(iterable, r=None)
</syntaxhighlight>

== المعاملات ==
=== <code>iterable</code> ===
الكائن القابل للتّكرار.

=== <code>r</code> ===
طول التّبادلات التي ستُنتَج.
قيمته الافتراضيّة هي القيمة <code>None</code>  إن لم تُمرّر له أيّة قيمة، فستكون قيمته هي طول الكائن <code>iterable</code> وستُولَّد جميع التّبادلات كاملة الطّول (full-length) المُمكنة.

== القيمة المعادة ==
صفوف بالطول المُعطى للمُعامل <code>r</code> تحتوي على تبادلات للعناصر المتواجدة في الكائن القابل للتّكرار المُعطى.

== أمثلة ==
المثال التّالي يوضّح كيفيّة عمل هذه الدّالة:
<syntaxhighlight lang="python3">
>>> list(itertools.permutations('ABC', 2))
[('A', 'B'), ('A', 'C'), ('B', 'A'), ('B', 'C'), ('C', 'A'), ('C', 'B')]
</syntaxhighlight>

== ملاحظات ==
الدّالة مُكافئة لما يلي:
<syntaxhighlight lang="python3">
def permutations(iterable, r=None):
    # permutations('ABCD', 2) --> AB AC AD BA BC BD CA CB CD DA DB DC
    # permutations(range(3)) --> 012 021 102 120 201 210
    pool = tuple(iterable)
    n = len(pool)
    r = n if r is None else r
    if r > n:
        return
    indices = list(range(n))
    cycles = list(range(n, n-r, -1))
    yield tuple(pool[i] for i in indices[:r])
    while n:
        for i in reversed(range(r)):
            cycles[i] -= 1
            if cycles[i] == 0:
                indices[i:] = indices[i+1:] + indices[i:i+1]
                cycles[i] = n - i
            else:
                j = cycles[i]
                indices[i], indices[-j] = indices[-j], indices[i]
                yield tuple(pool[i] for i in indices[:r])
                break
        else:
            return
</syntaxhighlight>

يُمكن كذلك تمثيل شيفرة الدّالة <code>itertools.permutations()‎</code> كتسلسل فرعيّ للدّالة <code>itertools.product()‎</code> بعد ترشيحها لإزالة الخانات التي تحتوي على عناصر مُكرَّرة (أي تلك التي لديها نفس الموقع في مسبح المُدخلات):
<syntaxhighlight lang="python3">
def permutations(iterable, r=None):
    pool = tuple(iterable)
    n = len(pool)
    r = n if r is None else r
    for indices in product(range(n), repeat=r):
        if len(set(indices)) == r:
            yield tuple(pool[i] for i in indices)
</syntaxhighlight>

عدد العناصر المُعادة هو <code>n! / r! / (n-r)!‎</code> عند <code>0 <= r <= n</code> أو صفرًا عند <code>r > n</code>.

== انظر أيضًا ==
* [[Python/iterators|المكرِّرات Iterators في بايثون]]
* [[Python/generators|المولدات Generators في بايثون]].
* [[Python/itertools/product|<code>itertools.product</code>]]: تُعيد حاصل الضرب المباشر.

== مصادر ==
* [https://docs.python.org/3/library/itertools.html#itertools.permutations قسم الدالة itertools.permutations في توثيق Python الرسمي].
[[تصنيف:Python]]
[[تصنيف:Python Function]]
[[تصنيف:Python Modules]]
[[تصنيف:Python itertools]]